docs: improve developer experience — build deps, dev workflow, Zed tasks

README.md

@@ -78,6 +78,7 @@ nteract/desktop
 │   ├── runtimed-py/       # Python bindings for the daemon
 │   ├── runtimed-wasm/     # WASM Automerge bindings for frontend (same automerge crate as daemon)
 │   ├── notebook/          # Notebook Tauri app
+│   ├── notebook-doc/      # Shared Automerge document operations (cells, metadata, sync)
 │   ├── sidecar/           # Sidecar wry/tao app
 │   ├── tauri-jupyter/     # Shared Tauri/Jupyter utilities
 │   ├── kernel-launch/     # Shared kernel launching API
@@ -149,6 +150,16 @@ The underlying Rust libraries are published to crates.io:
 - [`runtimelib`](https://crates.io/crates/runtimelib) — Jupyter kernel interactions over ZeroMQ
 - [`nbformat`](https://crates.io/crates/nbformat) — Notebook parsing
 
+## Contributing
+
+See the `contributing/` directory for detailed guides:
+
+- [Development workflow](contributing/development.md) — build commands, dev daemon, Zed tasks
+- [Architecture](contributing/architecture.md) — runtime principles, daemon, state, sync
+- [Protocol](contributing/protocol.md) — wire protocol, magic bytes preamble, version negotiation
+- [Releasing](contributing/releasing.md) — versioning scheme, release procedures, tag conventions
+- [Testing](contributing/testing.md) — Vitest, Rust, Python, E2E
+
 ## License
 
 BSD-3-Clause

contributing/build-dependencies.md

@@ -6,9 +6,8 @@ each other. The key insight: the Notebook app (Tauri) bundles `runtimed` and
 step. Similarly, frontend assets must be built before their consuming Rust crates
 compile.
 
-> **Note:** PR [#209](https://github.com/nteract/desktop/pull/209) improves the
-> dev workflow so `cargo xtask dev` handles the sidecar binary build
-> automatically, but for release builds the dependency chain below still applies.
+> **Note:** `cargo xtask dev` handles the sidecar binary build automatically
+> in development. For release builds the dependency chain below still applies.
 
 ## Full Build Dependency Graph
 
@@ -21,12 +20,14 @@ graph TD
 
     subgraph "Rust Crates (Cargo workspace)"
         TJ["tauri-jupyter<br/><i>shared Jupyter types</i>"]
+        ND["notebook-doc<br/><i>shared Automerge doc ops</i>"]
         RD["runtimed (lib + bin)<br/><i>daemon</i>"]
         SC["sidecar (lib + bin)<br/><i>output viewer</i>"]
         RC["runt-cli (bin: runt)<br/><i>CLI</i>"]
         NB["notebook (Tauri app)<br/><i>main app</i>"]
         XT["xtask<br/><i>build orchestrator</i>"]
         RWASM["runtimed-wasm<br/><i>WASM notebook doc ops</i>"]
+        RDPY["runtimed-py<br/><i>Python bindings</i>"]
     end
 
     subgraph "Bundled Artifacts"
@@ -42,17 +43,20 @@ graph TD
     %% Rust crate dependencies (path deps in Cargo.toml)
     TJ -->|"path dep"| SC
     TJ -->|"path dep"| NB
+    ND -->|"path dep"| RD
+    ND -->|"path dep"| RWASM
+    ND -->|"path dep"| RDPY
     RD -->|"path dep"| NB
     RD -->|"path dep"| RC
-    SC -->|"path dep"| RC
+    RD -->|"path dep"| RDPY
 
     %% External binary bundling (not a Cargo dep — a Tauri bundle dep)
     RD -.->|"binary copied to<br/>crates/notebook/binaries/"| APP
     RC -.->|"binary copied to<br/>crates/notebook/binaries/"| APP
     NB -->|"cargo tauri build"| APP
 
     %% Python package
-    RC -->|"maturin build<br/>(bindings = bin)"| PY
+    RDPY -->|"maturin build<br/>(bindings = pyo3)"| PY
     SUI -->|"embedded via<br/>rust-embed in sidecar crate"| PY
 
     %% xtask orchestrates everything
@@ -65,7 +69,7 @@ graph TD
     classDef artifact fill:#e8f5e9,stroke:#2e7d32
 
     class SUI,NUI frontend
-    class TJ,RD,SC,RC,NB,XT,RWASM rust
+    class TJ,ND,RD,SC,RC,NB,XT,RWASM,RDPY rust
     class APP,PY artifact
 ```
 
@@ -99,6 +103,7 @@ graph BT
     SC["sidecar"]
     RC["runt-cli"]
     NB["notebook"]
+    ND["notebook-doc"]
     XT["xtask"]
     KL["kernel-launch"]
     KE["kernel-env"]
@@ -115,9 +120,12 @@ graph BT
     NB -->|"depends on"| RT
     NB -->|"depends on"| RW
     RC -->|"depends on"| RD
+    RC -->|"depends on"| RW
+    RD -->|"depends on"| ND
     RD -->|"depends on"| KL
     RD -->|"depends on"| KE
     RDPY -->|"depends on"| RD
+    RWASM -->|"depends on"| ND
 
     classDef standalone fill:#fff9c4,stroke:#f9a825
     classDef leaf fill:#c8e6c9,stroke:#388e3c
@@ -126,7 +134,7 @@ graph BT
     class TJ,KL,KE,RT,RW,RWASM standalone
     class XT standalone
     class NB,RC,RDPY leaf
-    class RD shared
+    class RD,ND shared
 ```
 
 ## Key Points
@@ -139,4 +147,5 @@ graph BT
 | `isolated-renderer` built inline | The notebook-ui Vite plugin builds the isolated renderer and embeds it as a virtual module — no separate build step needed |
 | `xtask` has no Cargo deps | It shells out to `cargo build`, `pnpm`, and `cargo tauri` to orchestrate the full build |
 | `runtimed-wasm` must build before `notebook-ui` | wasm-pack output lands in `apps/notebook/src/wasm/runtimed-wasm/`; Vite imports it at build time. Artifacts are committed to the repo, so this step is only needed when changing `crates/runtimed-wasm/`. |
-| Python wheel uses maturin | `python/runtimed/pyproject.toml` points `maturin` at `crates/runt/Cargo.toml` with `bindings = "bin"` |
+| Python wheel uses maturin | `python/runtimed/pyproject.toml` points `maturin` at `crates/runtimed-py/Cargo.toml` with `bindings = "pyo3"` |
+| `notebook-doc` is shared | `crates/notebook-doc/` provides Automerge document operations used by `runtimed`, `runtimed-wasm`, and `runtimed-py` — the single source of truth for cell mutations |

contributing/development.md

@@ -158,7 +158,13 @@ RUNTIMED_DEV=1 cargo xtask dev
 
 Per-worktree state is stored in `~/.cache/runt/worktrees/{hash}/`.
 
-**For AI agents:** Use `./target/debug/runt` directly to interact with the daemon. See the "Agent Access to Dev Daemon" section in AGENTS.md.
+**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:
+
+```bash
+export RUNTIMED_DEV=1
+export RUNTIMED_WORKSPACE_PATH="$(pwd)"
+./target/debug/runt daemon status
+```
 
 ### Testing Against System Daemon (Production Mode)
 
@@ -201,3 +207,45 @@ If the app says "Dev daemon not running":
 - Run `cargo xtask dev-daemon` in another terminal first
 
 See [contributing/runtimed.md](./runtimed.md) for full daemon development docs.
+
+## Before You Commit
+
+CI rejects PRs that fail formatting. Run these before every commit:
+
+```bash
+# Format Rust
+cargo fmt
+
+# Format and lint TypeScript/JavaScript
+npx @biomejs/biome check --fix apps/notebook/src/ e2e/
+```
+
+Use [conventional commits](https://www.conventionalcommits.org/) for commit messages and PR titles:
+
+```
+feat(kernel): add environment source labels
+fix(runtimed): handle missing daemon socket
+docs(agents): enforce conventional commit format
+```
+
+## Zed Editor Integration
+
+The repo includes `.zed/tasks.json` with pre-configured tasks that set the correct environment variables for dev mode. Use `task: spawn` (cmd-shift-t) to run them:
+
+| Task | What it does |
+|------|-------------|
+| **Dev Daemon** | `cargo xtask dev-daemon` with `RUNTIMED_DEV=1` and `RUNTIMED_WORKSPACE_PATH` |
+| **Dev App** | `cargo xtask dev` with dev env vars and auto-assigned Vite port |
+| **Daemon Status** | `./target/debug/runt daemon status` pointed at the worktree daemon |
+| **Daemon Logs** | `./target/debug/runt daemon logs -f` with live tail |
+| **Format** | `cargo fmt` + biome in one step |
+| **Setup** | `pnpm install && cargo xtask build` for first-time setup |
+
+The tasks use `$ZED_WORKTREE_ROOT` for `RUNTIMED_WORKSPACE_PATH`, giving each Zed worktree its own isolated daemon — no conflicts when working across branches.
+
+**For agents in Zed:** The Zed task env vars aren't available in agent terminal sessions. Set them explicitly:
+
+```bash
+export RUNTIMED_DEV=1
+export RUNTIMED_WORKSPACE_PATH="/path/to/your/worktree"
+```