hypernote 0.3.0__tar.gz → 0.4.1__tar.gz

{hypernote-0.3.0 → hypernote-0.4.1}/.gitignore

@@ -18,4 +18,6 @@ lib/
 .jupyter/
 .agent-repl/
 tmp/
-vscode-extension/out/
+vscode-extension/
+dev/vscode-extension.md
+docs/vscode-extension.md

hypernote-0.4.1/AGENTS.md

@@ -0,0 +1,56 @@
+# Hypernote
+
+Notebook-first execution system built on top of Jupyter shared documents.
+
+## Operator Quick Start
+
+Use this path when you are creating, running, recovering, or opening notebooks.
+You can stop after this section unless you are changing Hypernote itself.
+
+```bash
+uv run hypernote setup doctor
+# If no Hypernote API is reachable, start the server from this repo.
+# Omit --no-browser when you want setup to open JupyterLab immediately.
+uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  uv run hypernote setup doctor | grep -q '"hypernote_api"[[:space:]]*:[[:space:]]*"ok"' && break
+  sleep 0.5
+done
+uv run hypernote setup doctor
+notebook_path="tmp/demo-$(date +%Y%m%d-%H%M%S).ipynb"
+uv run hypernote create "$notebook_path" --empty --brief
+uv run hypernote ix "$notebook_path" -s 'value = 20 + 22; print(value)' --brief
+uv run hypernote status "$notebook_path" --brief
+```
+
+Use the notebook path the task actually needs. The `tmp/demo-...` path above is
+only a disposable example for tests and agent smoke checks.
+
+`--brief` keeps cell `output_preview` while omitting command hints, snapshot
+tokens, and bulky raw output payloads. If the preview is too small, use a
+focused read instead of reading the whole notebook:
+
+```bash
+uv run hypernote cat "$notebook_path" --output CELL_ID --brief --full-output
+```
+
+To hand the notebook to a browser, open:
+
+```text
+<server-from-setup-doctor>/lab/tree/<notebook-path>
+```
+
+## Operator Docs
+
+- [SKILL.md](SKILL.md)
+- [docs/README.md](docs/README.md)
+- [docs/getting-started.md](docs/getting-started.md)
+- [docs/cli.md](docs/cli.md)
+- [docs/sdk.md](docs/sdk.md)
+
+## Contributor Docs
+
+If you are editing Hypernote code, tests, architecture, releases, or project
+guidance, read [dev/agent-contributor.md](dev/agent-contributor.md). That file
+contains the architecture map, code ownership notes, verification matrix, and
+release rules intentionally omitted from this operator-facing quick path.

{hypernote-0.3.0 → hypernote-0.4.1}/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.4.1 - 2026-05-25
+
+Hypernote now has a low-noise operator path for agents: create notebooks,
+execute cells, inspect focused outputs, and hand off to JupyterLab without
+filling context with server logs, hints, snapshots, or raw notebook payloads.
+
+### Added
+
+- `--brief` output for `create`, `ix`, `exec`, `status`, `cat`, and
+  `edit replace`, preserving useful cell output previews while omitting bulky
+  command hints, snapshots, raw payloads, and per-cell batch chatter.
+- `CellStatus.from_handle(cell)` for SDK-owned cell observation shaping from a
+  live `CellHandle`.
+- Focused operator guidance for headless notebook setup, execution, recovery,
+  batch mode, SDK use, and browser handoff.
+
+### Changed
+
+- `SKILL.md` and `AGENTS.md` now prioritize operator workflows; contributor
+  architecture, release, and verification guidance moved to
+  `dev/agent-contributor.md`.
+- Headless setup recipes now redirect long-running server logs and wait briefly
+  for `setup doctor` readiness after backgrounding `setup serve`.
+- Deferred VS Code extension artifacts are ignored until that surface is ready
+  to ship.
+
+### Fixed
+
+- Stream output previews now normalize list-shaped Jupyter stream text and
+  strip ANSI color sequences.
+- Brief execution output avoids presenting stale cell outputs as fresh when a
+  job was launched with `--no-wait`.
+- `ix --brief` and `exec --brief` reject incompatible streaming or human output
+  modes before mutating notebook state.
+
+## 0.4.0 - 2026-05-10
+
+Hypernote now treats Jupyter's real-time collaboration journal as temporary
+server-local state for `setup serve`, keeping the `.ipynb` notebook file as the
+only durable project artifact.
+
+### Changed
+
+- `hypernote setup serve` now configures Jupyter RTC to use temporary
+  collaboration journal storage instead of Jupyter's default project-root
+  `.jupyter_ystore.db` SQLite database.
+- Live-server and browser regression fixtures now launch with the same
+  temporary journal policy as `setup serve`, including coverage that notebook
+  execution does not create `.jupyter_ystore.db` in the server root.
+- Project guidance now distinguishes the durable **Notebook File** from the
+  temporary **Collaboration Journal**, and documents the crash-recovery tradeoff
+  for unsaved live shared-document changes.
+
 ## 0.3.0 - 2026-05-10
 
 Hypernote is now a JupyterLab-first integration: the default install carries the

{hypernote-0.3.0 → hypernote-0.4.1}/CONTEXT.md

@@ -9,6 +9,14 @@ server so agents and humans can work against one notebook truth.
 The server-side notebook document that all Hypernote operations use as the live notebook truth.
 _Avoid_: file-only notebook truth
 
+**Notebook File**:
+The `.ipynb` artifact that persists notebook contents and outputs after the Shared Document is saved.
+_Avoid_: Hypernote database, collaboration store, job history
+
+**Collaboration Journal**:
+The Jupyter real-time collaboration update store used as recoverability cache for live Shared Document state.
+_Avoid_: notebook primary storage, Hypernote job history, attribution store
+
 **Hypernote JupyterLab Server**:
 A JupyterLab server launched or verified with Hypernote's required server and collaboration extensions.
 _Avoid_: plain Jupyter server, separate agent server
@@ -24,6 +32,8 @@ _Avoid_: separate runtime mode
 ## Relationships
 
 - A **Hypernote JupyterLab Server** owns the **Shared Document**.
+- A **Shared Document** saves durable notebook contents and outputs into one **Notebook File**.
+- A **Collaboration Journal** is temporary server-local state; Hypernote does not make it a durable project artifact or product choice.
 - An **Open Lab Tab** and **Agent Automation** must attach to the same **Hypernote JupyterLab Server**.
 - **Agent Automation** does not require an **Open Lab Tab**, but it still requires the **Hypernote JupyterLab Server**.
 
@@ -31,8 +41,13 @@ _Avoid_: separate runtime mode
 
 > **Dev:** "Can agents run notebooks without JupyterLab?"
 > **Domain expert:** "No separate mode: agents use the **Hypernote JupyterLab Server** even if nobody has an **Open Lab Tab**."
+>
+> **Dev:** "Is the collaboration database part of Hypernote's durable state?"
+> **Domain expert:** "No — durability means the **Shared Document** has saved back to the **Notebook File**."
 
 ## Flagged Ambiguities
 
 - Agent work without an **Open Lab Tab** was previously described as a separate product mode; resolved: Hypernote only distinguishes whether an **Open Lab Tab** exists.
 - "Jupyter server" was used broadly; resolved: the supported product server is a **Hypernote JupyterLab Server**.
+- Jupyter's real-time collaboration store was treated as possible Hypernote state; resolved: it is a **Collaboration Journal**, not primary notebook storage or Hypernote job history.
+- Persistent collaboration-store configuration was considered as a user-facing choice; resolved: Hypernote treats the **Collaboration Journal** as temporary server-local state only.

{hypernote-0.3.0 → hypernote-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypernote
-Version: 0.3.0
+Version: 0.4.1
 Summary: Thin control plane for Jupyter notebook execution with jobs, attribution, and runtime lifecycle
 Project-URL: Homepage, https://github.com/gilad-rubin/hypernote
 Project-URL: Repository, https://github.com/gilad-rubin/hypernote
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 - **One notebook truth** - notebook edits, execution, and late-open JupyterLab views all operate on the same logical document.
 - **Agent-first surface** - the Python SDK is primary, and the CLI is a thin shell over it.
 - **Ephemeral control plane** - Jupyter owns durable `.ipynb` contents and outputs; Hypernote owns in-memory runtimes, jobs, and attribution.
+- **Temporary collaboration journal** - `setup serve` keeps Jupyter RTC updates in server-local temp storage, not repo-root databases.
 
 ## What it ships
 
@@ -44,22 +45,34 @@ Description-Content-Type: text/markdown
 
 ```bash
 uv sync
-uv run hypernote --help
-uv run hypernote setup serve
 uv run hypernote setup doctor
-uv run hypernote create tmp/demo.ipynb
-uv run hypernote ix tmp/demo.ipynb -s 'value = 20 + 22\nprint(value)'
-uv run hypernote status tmp/demo.ipynb --full
+# If no Hypernote API is reachable, start the server from this repo.
+# Omit --no-browser when you want setup to open JupyterLab immediately.
+uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  uv run hypernote setup doctor | grep -q '"hypernote_api"[[:space:]]*:[[:space:]]*"ok"' && break
+  sleep 0.5
+done
+uv run hypernote setup doctor
+notebook_path="tmp/demo-$(date +%Y%m%d-%H%M%S).ipynb"
+uv run hypernote create "$notebook_path" --empty --brief
+uv run hypernote ix "$notebook_path" -s 'value = 20 + 22; print(value)' --brief
+uv run hypernote status "$notebook_path" --brief
 ```
 
+Use the notebook path you actually want. The `tmp/demo-...` path above is only a
+disposable example that avoids overwriting an existing notebook.
+`--brief` keeps the cell's `output_preview` while omitting hints, snapshot
+tokens, and bulky raw output payloads.
+
 For another repo's environment, install Hypernote there (`uv add hypernote --dev`) and run
-the same bootstrap command from that repo.
+`setup doctor` / `setup serve` from that repo so kernels and notebook paths line up.
 
 ## Install
 
 The default install includes the JupyterLab integration stack Hypernote needs:
 JupyterLab, shared-document support, server-side notebook execution, and the
-collaboration/docprovider frontend packages.
+Hypernote server extension.
 
 Use `hypernote[dev]` only for local development and CI tooling.
 
@@ -76,6 +89,7 @@ Jupyter owns:
 
 - notebook persistence
 - shared YDoc document state
+- temporary collaboration journal state for live RTC updates
 - kernel and session primitives
 - notebook rendering in JupyterLab
 
@@ -86,7 +100,7 @@ Hypernote owns:
 - actor attribution
 - SDK, CLI, and thin REST handlers
 
-## Design discipline
+## Contributor discipline
 
 - shared behavior should have one owner, usually the SDK for agent-facing observation rules
 - command and payload variants should preserve one contract unless a difference is explicit and documented
@@ -95,12 +109,21 @@ Hypernote owns:
 
 ## Documentation
 
+Operator docs:
+
 - [Getting Started](docs/getting-started.md)
 - [CLI Reference](docs/cli.md)
 - [SDK Reference](docs/sdk.md)
+
+Contributor and advanced behavior docs:
+
+- [Agent Contributor Guide](dev/agent-contributor.md)
 - [Runtime Model](docs/runtime-model.md)
 - [Browser Regression Spec](docs/browser-regression-spec.md)
 
+Agents that only need to create, run, recover, or open notebooks can stop after
+the operator docs.
+
 ## Verification
 
 For local development and CI, install the dev tier first:

{hypernote-0.3.0 → hypernote-0.4.1}/README.md

@@ -4,6 +4,7 @@
 - **One notebook truth** - notebook edits, execution, and late-open JupyterLab views all operate on the same logical document.
 - **Agent-first surface** - the Python SDK is primary, and the CLI is a thin shell over it.
 - **Ephemeral control plane** - Jupyter owns durable `.ipynb` contents and outputs; Hypernote owns in-memory runtimes, jobs, and attribution.
+- **Temporary collaboration journal** - `setup serve` keeps Jupyter RTC updates in server-local temp storage, not repo-root databases.
 
 ## What it ships
 
@@ -19,22 +20,34 @@
 
 ```bash
 uv sync
-uv run hypernote --help
-uv run hypernote setup serve
 uv run hypernote setup doctor
-uv run hypernote create tmp/demo.ipynb
-uv run hypernote ix tmp/demo.ipynb -s 'value = 20 + 22\nprint(value)'
-uv run hypernote status tmp/demo.ipynb --full
+# If no Hypernote API is reachable, start the server from this repo.
+# Omit --no-browser when you want setup to open JupyterLab immediately.
+uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  uv run hypernote setup doctor | grep -q '"hypernote_api"[[:space:]]*:[[:space:]]*"ok"' && break
+  sleep 0.5
+done
+uv run hypernote setup doctor
+notebook_path="tmp/demo-$(date +%Y%m%d-%H%M%S).ipynb"
+uv run hypernote create "$notebook_path" --empty --brief
+uv run hypernote ix "$notebook_path" -s 'value = 20 + 22; print(value)' --brief
+uv run hypernote status "$notebook_path" --brief
 ```
 
+Use the notebook path you actually want. The `tmp/demo-...` path above is only a
+disposable example that avoids overwriting an existing notebook.
+`--brief` keeps the cell's `output_preview` while omitting hints, snapshot
+tokens, and bulky raw output payloads.
+
 For another repo's environment, install Hypernote there (`uv add hypernote --dev`) and run
-the same bootstrap command from that repo.
+`setup doctor` / `setup serve` from that repo so kernels and notebook paths line up.
 
 ## Install
 
 The default install includes the JupyterLab integration stack Hypernote needs:
 JupyterLab, shared-document support, server-side notebook execution, and the
-collaboration/docprovider frontend packages.
+Hypernote server extension.
 
 Use `hypernote[dev]` only for local development and CI tooling.
 
@@ -51,6 +64,7 @@ Jupyter owns:
 
 - notebook persistence
 - shared YDoc document state
+- temporary collaboration journal state for live RTC updates
 - kernel and session primitives
 - notebook rendering in JupyterLab
 
@@ -61,7 +75,7 @@ Hypernote owns:
 - actor attribution
 - SDK, CLI, and thin REST handlers
 
-## Design discipline
+## Contributor discipline
 
 - shared behavior should have one owner, usually the SDK for agent-facing observation rules
 - command and payload variants should preserve one contract unless a difference is explicit and documented
@@ -70,12 +84,21 @@ Hypernote owns:
 
 ## Documentation
 
+Operator docs:
+
 - [Getting Started](docs/getting-started.md)
 - [CLI Reference](docs/cli.md)
 - [SDK Reference](docs/sdk.md)
+
+Contributor and advanced behavior docs:
+
+- [Agent Contributor Guide](dev/agent-contributor.md)
 - [Runtime Model](docs/runtime-model.md)
 - [Browser Regression Spec](docs/browser-regression-spec.md)
 
+Agents that only need to create, run, recover, or open notebooks can stop after
+the operator docs.
+
 ## Verification
 
 For local development and CI, install the dev tier first:

hypernote-0.4.1/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: hypernote
+description: Work against Hypernote's notebook-first SDK and agent-first CLI. Use this when an agent needs to create notebooks, insert or edit cells, run code without an open Lab tab, inspect notebook status or diffs, or verify JupyterLab attach/streaming behavior.
+---
+
+# hypernote
+
+`hypernote` is the notebook runtime surface. The SDK is the core API. The CLI is a thin shell over that SDK.
+
+Run `uv run hypernote` for a live workspace dashboard when you need
+orientation. Use `--help` only as an explicit discovery fallback when the task
+is not covered by this skill or the docs.
+
+## Prerequisite
+
+Hypernote CLI requires two things:
+
+1. **`hypernote` installed in the current repo's environment.**
+   If `uv run hypernote setup doctor` fails because the command is missing,
+   install it first:
+   ```bash
+   uv add hypernote --dev
+   ```
+
+2. **A running Hypernote-enabled JupyterLab server.**
+   See "Server lifecycle" below.
+
+Once both are in place, all commands are just `uv run hypernote ...`.
+
+## Server lifecycle
+
+One server serves all notebooks and all agents in a workspace. Do not start multiple servers.
+
+**Check if a server is already running:**
+
+```bash
+uv run hypernote setup doctor
+```
+
+For headless CLI/SDK work, the important fields are `hypernote_api`,
+`jupyter_server_nbmodel`, `jupyter_server_ydoc`, and `jobs_endpoint`. If those
+are usable and `default_kernel` is plausible for the repo, use the server.
+`default_kernel` may be a kernelspec name such as `python` or an interpreter
+path. `jupyter_collaboration` or `jupyter_docprovider` showing `missing` is not
+by itself a blocker for headless execution; investigate those only when browser
+or JupyterLab collaboration behavior is failing.
+
+**If no server is running, start one from the repo that owns the notebook:**
+
+```bash
+uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &
+```
+
+`setup serve` is a foreground process. Agents that need to keep working should
+background it and redirect logs. The default address is `http://127.0.0.1:8888`.
+Omit `--no-browser` when the user wants JupyterLab opened as part of setup; use
+`--no-browser` only for quiet headless automation or when you will open a
+specific notebook URL yourself.
+
+Servers launched by `setup serve` use temporary Jupyter collaboration journal storage.
+Notebook contents and outputs still persist through the `.ipynb` file once the
+shared document is saved.
+
+**If the server is running but `default_kernel` points to the wrong Python** (e.g., a
+different repo's `.venv`), stop the old server and start a new one with `setup serve`
+from this repo. This is the only case where you should restart a running server.
+
+To stop the server: press `Ctrl+C` in the terminal where `setup serve` is running, or
+if it's backgrounded, find its pid with `lsof -ti :8888` and kill it.
+
+**If port 8888 is taken**, use a different port and point all commands at it:
+
+```bash
+uv run hypernote setup serve --port 8889 --no-browser > tmp/hypernote-serve-8889.log 2>&1 &
+uv run hypernote --server http://127.0.0.1:8889 setup doctor
+```
+
+## Quick Start
+
+Pick the notebook path from the user's request. If the user did not ask for a
+specific path, use a unique disposable path under `tmp/` so examples and agent
+runs do not overwrite each other.
+
+```bash
+uv run hypernote                   # live workspace dashboard and hints
+uv run hypernote setup doctor            # check for existing server
+uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &  # only if the API is unreachable and quiet headless setup is desired
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  uv run hypernote setup doctor | grep -q '"hypernote_api"[[:space:]]*:[[:space:]]*"ok"' && break
+  sleep 0.5
+done
+uv run hypernote setup doctor            # readiness check after a cold start
+notebook_path="tmp/demo-$(date +%Y%m%d-%H%M%S).ipynb"
+uv run hypernote create "$notebook_path" --empty --brief
+uv run hypernote ix "$notebook_path" -s 'value = 20 + 22' --brief
+uv run hypernote status "$notebook_path" --brief
+```
+
+## Fast Agent Smoke Test
+
+When the task is simply to prove headless execution and optionally open the
+result in JupyterLab, keep the workflow to the product path. Use the path the
+user requested; the `tmp/` path below is only for disposable smoke tests:
+
+```bash
+uv run hypernote setup doctor
+# only if the Hypernote API is unreachable and you do not want setup to open Lab:
+uv run hypernote setup serve --no-browser > tmp/hypernote-serve.log 2>&1 &
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  uv run hypernote setup doctor | grep -q '"hypernote_api"[[:space:]]*:[[:space:]]*"ok"' && break
+  sleep 0.5
+done
+uv run hypernote setup doctor
+notebook_path="tmp/demo-$(date +%Y%m%d-%H%M%S).ipynb"
+uv run hypernote create "$notebook_path" --empty --brief
+uv run hypernote ix "$notebook_path" -s 'value = 20 + 22; print(value)' --brief
+```
+
+Run `setup serve` only when `setup doctor` shows the Hypernote API is
+unreachable or the server belongs to the wrong environment. If you start the
+server from an agent, redirect its output to `tmp/*.log`; Jupyter startup,
+autosave, kernel, and 404 messages are operational noise unless the server
+failed to start.
+
+If the user asks to open JupyterLab during setup, omit `--no-browser`. If they
+ask to open the resulting notebook, use the browser handoff URL below after the
+headless command succeeds.
+
+To hand the notebook to a browser or UI surface, open:
+
+```text
+<server-from-setup-doctor>/lab/tree/<notebook-path>
+```
+
+URL-encode path segments that contain spaces or special URL characters. Simple
+workspace-relative paths such as `tmp/demo.ipynb` can be used directly.
+
+For a smoke test, do not inspect broad docs, run command help, or stream server
+logs unless the direct path fails and that information is needed for recovery.
+Browser automation is only the final handoff step; Hypernote work should happen
+through `setup serve`, `create`, and `ix`.
+
+## Common Agent Recipes
+
+Use these compact paths before reaching for `--help` or broad notebook reads.
+For agent loops, add `--brief` to `create`, `ix`, `exec`, `status`,
+`edit replace`, and focused `cat` reads when you want the cell result without
+command hints, snapshot tokens, raw output payloads, or per-cell batch chatter.
+`--brief` still preserves `output_preview`; use the full command or
+`cat --output CELL_ID --brief --full-output` when the preview is not enough.
+
+- **Iterative multi-line work:** `create --empty`, then pipe each substantial
+  cell into `ix` with a heredoc. Inspect the just-run cell with
+  `cat --output CELL_ID --brief` before deciding the next `ix`. If the output
+  preview is truncated or the full result matters, use
+  `cat --output CELL_ID --brief --full-output`; this is still a focused cell read.
+  `CELL_ID` is the id reported by the preceding `ix` result. In `--brief`
+  output, use `cell_ids[0]` or `cells[].id`; in the full output, use
+  `inserted_cells[].id` or `job.cell_ids`. If automating extraction, parse that
+  JSON field; do not infer the id from notebook order.
+- **Failed cell recovery:** read the failed cell output, replace the same cell,
+  then execute it again:
+  ```bash
+  uv run hypernote cat nb.ipynb --output CELL_ID --brief
+  uv run hypernote edit replace nb.ipynb CELL_ID -s 'print("fixed")' --brief
+  uv run hypernote exec nb.ipynb CELL_ID --brief
+  ```
+  `edit replace` changes source without running it; old outputs may remain until
+  the following `exec`.
+- **Known-good batch:** use `ix --cells-file` only when intermediate inspection
+  is unnecessary. Batch output may contain one compact result for each executed
+  code cell plus a final aggregate; markdown cells are represented in the final
+  aggregate. The file is a JSON array of cell objects:
+  ```json
+  [
+    {"id": "setup", "type": "code", "source": "value = 21 * 2\nprint(value)"},
+    {"type": "code", "source": "print('batch-ok')"}
+  ]
+  ```
+  Each object supports `source`, optional `type` or `cell_type` (`code` or
+  `markdown`), and optional `id`.
+  ```bash
+  uv run hypernote ix "$notebook_path" --cells-file tmp/cells.json --brief
+  ```
+- **SDK happy path:** use one short Python script that connects, inserts,
+  runs, waits, and prints `nb.status().summary`. Use `nb.status(full=True)` only
+  when you need full source/output details. For proof of a single cell's output,
+  call `nb.status().cell(cell.id).output_preview(full_output=True)`.
+
+## Core Workflow
+
+The normal way to build and run a notebook is one cell at a time:
+
+```text
+ix  →  read output  →  decide next cell  →  ix  →  repeat
+```
+
+This is the happy path. Insert a cell, run it, observe the output, then decide what comes next.
+Do not pre-plan all cells and batch-insert them. Work iteratively.
+
+### Passing cell source
+
+Three input modes, from simplest to most robust:
+
+1. **Inline** for short single-line cells:
+   ```bash
+   uv run hypernote ix nb.ipynb -s 'print("hello")'
+   ```
+
+2. **Stdin with heredoc** for multi-line cells (preferred for anything non-trivial):
+   ```bash
+   cat <<'EOF' | uv run hypernote ix nb.ipynb
+   import pandas as pd
+   df = pd.read_csv("data.csv")
+   print(df.head())
+   EOF
+   ```
+
+3. **Source file** when the cell is very large or already on disk:
+   ```bash
+   uv run hypernote ix nb.ipynb --source-file path/to/cell.py
+   ```
+
+Do not use `-s` for multi-line code. Shell quoting will corrupt newlines.
+
+### Commands
+
+- `ix` — insert a cell and run it. This is the primary command.
+- `exec` — re-run an existing cell by id (useful after editing a failed cell)
+- `edit` — mutate cell source or structure without executing
+- `run-all` / `restart` / `restart-run-all` — notebook-wide execution
+- `status` / `diff` / `cat` — inspect notebook state and outputs with summary-first reads, filtered cells, and focused output flags
+
+### When a cell fails
+
+1. Read the error output from `ix`.
+2. Use `cat --cell <cell-id>` or `cat --output <cell-id>` if you need a compact view of the failure.
+3. Fix the source with `edit replace PATH CELL_ID -s '...'` or pipe new source through stdin.
+4. Re-run with `exec <cell-id>`.
+5. Continue with the next `ix`.
+
+Do not re-insert a failed cell. Edit it in place and re-execute.
+
+### `--cells-file` (batch mode)
+
+`ix --cells-file` inserts and runs multiple cells sequentially. Use it only for known-good
+cell sequences where you do not need to inspect intermediate outputs.
+
+If batch mode halts early (cell failure, interrupt, or input prompt), the output includes
+`halt_reason`, `last_processed_cell_id`, `cells_inserted`, and `cells_remaining` so you
+know exactly where to resume. Cells after the halt point were never inserted into the notebook.
+
+## Operator Practices
+
+1. Work iteratively: `ix` one cell, read the output, then decide the next cell.
+2. Use `create --empty` so you start with a clean notebook, not a Jupyter-inserted blank cell.
+3. Use heredoc or `--source-file` for multi-line cells. Never pass multi-line code through `-s`.
+4. Prefer the SDK and CLI over raw HTTP for notebook operation.
+5. Treat Jupyter shared documents as the source of truth. Open or closed JupyterLab tabs should show the same notebook result.
+6. For agents, prefer `--brief` output unless you intentionally need the fuller JSON payload.
+7. Start with `hypernote` itself when you need workspace context and the next best action.
+8. Use `--stream-json` only when you plan to watch the process; otherwise it wastes context.
+9. Start the server with `hypernote setup serve` instead of hand-writing Jupyter flags.
+10. Skip large rich outputs such as `graph.visualize()` in agent automation unless the visualization is the point of the run.
+11. Use unique notebook paths in smoke tests and demos.
+12. Move durable notes into `docs/` or `dev/`; keep `tmp/` disposable.
+13. Treat Hypernote jobs, runtime state, and cell attribution as ephemeral coordination state, not durable history.