hypernote 0.2.0__tar.gz → 0.4.0__tar.gz

hypernote-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,236 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g., 0.3.0)"
+        required: true
+        type: string
+      publish_to_pypi:
+        description: "Publish to PyPI"
+        required: true
+        default: true
+        type: boolean
+      create_draft:
+        description: "Create as draft release"
+        required: false
+        default: false
+        type: boolean
+  push:
+    branches:
+      - master
+    paths:
+      - "CHANGELOG.md"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/release.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  resolve-version:
+    if: ${{ github.event_name != 'push' || github.actor != 'github-actions[bot]' }}
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.resolve.outputs.version }}
+      publish_to_pypi: ${{ steps.resolve.outputs.publish_to_pypi }}
+      create_draft: ${{ steps.resolve.outputs.create_draft }}
+      should_release: ${{ steps.resolve.outputs.should_release }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Resolve release version
+        id: resolve
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_PUBLISH_TO_PYPI: ${{ inputs.publish_to_pypi }}
+          INPUT_CREATE_DRAFT: ${{ inputs.create_draft }}
+        run: |
+          VERSION="$INPUT_VERSION"
+          if [ -z "$VERSION" ]; then
+            VERSION="$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])
+          PY
+          )"
+          fi
+
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$ ]]; then
+            echo "❌ Invalid version format: $VERSION"
+            echo "Expected semantic version (e.g., 0.3.0, 0.3.0-alpha.1)"
+            exit 1
+          fi
+
+          git fetch --tags --force
+          TAG="v$VERSION"
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            if [ "$GITHUB_EVENT_NAME" = "push" ] && [ "${GITHUB_RUN_ATTEMPT:-1}" = "1" ]; then
+              echo "ℹ️ $TAG already exists; nothing to release."
+              echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+              echo "publish_to_pypi=false" >> "$GITHUB_OUTPUT"
+              echo "create_draft=false" >> "$GITHUB_OUTPUT"
+              echo "should_release=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "ℹ️ $TAG already exists; continuing because this is a rerun/recovery attempt."
+          fi
+
+          echo "✅ Version format is valid: $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "publish_to_pypi=${INPUT_PUBLISH_TO_PYPI:-true}" >> "$GITHUB_OUTPUT"
+          echo "create_draft=${INPUT_CREATE_DRAFT:-false}" >> "$GITHUB_OUTPUT"
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+
+  release:
+    needs: resolve-version
+    if: ${{ needs.resolve-version.outputs.should_release == 'true' }}
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ needs.resolve-version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Ensure release version is checked in
+        env:
+          VERSION: ${{ needs.resolve-version.outputs.version }}
+        run: |
+          CURRENT_VERSION="$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          print(tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"])
+          PY
+          )"
+
+          if [ "$CURRENT_VERSION" = "$VERSION" ]; then
+            echo "✅ pyproject.toml already declares $VERSION"
+            exit 0
+          fi
+
+          if [ "$GITHUB_EVENT_NAME" != "workflow_dispatch" ]; then
+            echo "❌ pyproject.toml declares $CURRENT_VERSION, expected $VERSION"
+            exit 1
+          fi
+
+          sed -i -E "0,/^version = \".*\"/s//version = \"$VERSION\"/" pyproject.toml
+
+          if ! grep -q "version = \"$VERSION\"" pyproject.toml; then
+            echo "❌ Failed to update version in pyproject.toml"
+            exit 1
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          uv lock
+          git add pyproject.toml uv.lock
+          git commit -m "chore: bump version to v$VERSION"
+          CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+          git push origin "$CURRENT_BRANCH"
+          echo "✅ Version commit pushed"
+
+      - name: Build package
+        run: |
+          rm -rf dist/ build/ *.egg-info/
+          uv build
+          if [ ! -f dist/*.whl ] || [ ! -f dist/*.tar.gz ]; then
+            echo "❌ Build artifacts not found"
+            exit 1
+          fi
+          echo "✅ Package built"
+          ls -la dist/
+
+      - name: Verify package
+        run: |
+          uv run --isolated --no-project --with dist/*.whl python -c "import hypernote; print('ok')"
+          echo "✅ Package verified"
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist-${{ needs.resolve-version.outputs.version }}
+          path: dist/*
+          if-no-files-found: error
+
+      - name: Run tests
+        run: |
+          uv run --extra dev playwright install --with-deps chromium
+          uv run --extra dev python -m pytest -q
+
+      - name: Create and push tag
+        env:
+          VERSION: ${{ needs.resolve-version.outputs.version }}
+        run: |
+          TAG="v$VERSION"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git fetch --tags --force
+          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            TAG_TARGET="$(git rev-list -n 1 "$TAG")"
+            HEAD_SHA="$(git rev-parse HEAD)"
+            if [ "$TAG_TARGET" = "$HEAD_SHA" ]; then
+              echo "✅ $TAG already points at $HEAD_SHA; continuing."
+              exit 0
+            fi
+            echo "❌ $TAG points at $TAG_TARGET, not current HEAD $HEAD_SHA. Refusing to retag."
+            exit 1
+          fi
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+          echo "✅ Created and pushed tag $TAG"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CREATE_DRAFT: ${{ needs.resolve-version.outputs.create_draft }}
+        run: |
+          TAG="v${{ needs.resolve-version.outputs.version }}"
+          DRAFT_FLAG=""
+          if [ "$CREATE_DRAFT" = "true" ]; then
+            DRAFT_FLAG="--draft"
+          fi
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          else
+            gh release create "$TAG" dist/* \
+              --generate-notes \
+              --verify-tag \
+              $DRAFT_FLAG
+          fi
+
+      - name: Summary
+        run: |
+          echo "## Release Summary" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Version:** v${{ needs.resolve-version.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **PyPI:** ${{ needs.resolve-version.outputs.publish_to_pypi }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- **Draft:** ${{ needs.resolve-version.outputs.create_draft }}" >> "$GITHUB_STEP_SUMMARY"
+
+  publish-pypi:
+    needs:
+      - resolve-version
+      - release
+    if: ${{ needs.resolve-version.outputs.publish_to_pypi == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist-${{ needs.resolve-version.outputs.version }}
+          path: dist/
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

{hypernote-0.2.0 → hypernote-0.4.0}/AGENTS.md

@@ -37,11 +37,10 @@ Hypernote owns a thin control plane:
 - Jupyter extension wiring in [src/hypernote/server/extension.py](src/hypernote/server/extension.py)
 - ephemeral job and attribution ledger in [src/hypernote/actor_ledger.py](src/hypernote/actor_ledger.py)
 - subshell-aware execute/interrupt/restart in [src/hypernote/server/subshell.py](src/hypernote/server/subshell.py)
-- optional VS Code embedding surface in [vscode-extension/src/extension.ts](vscode-extension/src/extension.ts)
 
 Core rule: notebook edits and execution must operate on one logical document truth whether JupyterLab is closed, already open, or opened mid-run.
 
-Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb` model, but Hypernote's runtime state, job records, and cell attribution are intentionally in-memory and notebook-scoped.
+Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb` model, but Hypernote's runtime state, job records, cell attribution, and `setup serve` collaboration journal are intentionally ephemeral and notebook- or server-scoped.
 
 Concurrent-actor rule: JupyterLab and Hypernote share one notebook session and one kernel. Hypernote-driven cells run in an ipykernel subshell so the kernel's main shell stays responsive to native Lab actions. Hypernote's extension overrides `/api/kernels/{id}/interrupt` and `/api/kernels/{id}/restart` so Lab's Stop and Restart toolbar buttons reach the subshell-routed cell or perform the right cleanup. See [dev/current-architecture.md](dev/current-architecture.md) for the full mechanism.
 
@@ -80,7 +79,7 @@ Default CLI contract:
 - non-TTY: one compact final JSON result
 - explicit streaming only through `--watch` or `--stream-json`
 - summary-first read payloads should come from SDK-backed observation helpers, not CLI-only formatting rules
-- `setup serve` is the default local bootstrap path for a Hypernote-enabled Jupyter server
+- `setup serve` is the default local bootstrap path for a Hypernote-enabled JupyterLab server
 - `setup doctor --path PATH` is the preferred first diagnostic when server reachability,
   kernelspec selection, or runtime mismatch is unclear
 
@@ -100,23 +99,17 @@ Default CLI contract:
 - Normalize boundary inputs early. If upstream payloads can arrive in more than one valid shape, accept and normalize them at the adapter boundary rather than assuming a single representation.
 - Prefer unique notebook paths in tests and demos. Browser tests must also use unique JupyterLab workspace URLs.
 - Keep `tmp/` disposable. Durable notes belong in `docs/` or `dev/`, not `tmp/`.
+- Release every version through a PR (CHANGELOG move + version bump + lockfile refresh on a `release/vX.Y.Z` branch), never via direct push to master. The full process is in [dev/release.md](dev/release.md).
 
 ## Read These First
 
 - [SKILL.md](SKILL.md)
 - [docs/README.md](docs/README.md)
 - [dev/README.md](dev/README.md)
+- [dev/release.md](dev/release.md)
 
 ## If You Are Editing...
 
-### `vscode-extension/*`
-
-- keep the extension decoupled from Hypernote-specific notebook semantics
-- prefer embedding JupyterLab over recreating notebook behavior in VS Code
-- if the extension launches Jupyter itself, keep that process local, explicit, and easy to inspect
-- update [docs/vscode-extension.md](docs/vscode-extension.md)
-- update [dev/vscode-extension.md](dev/vscode-extension.md)
-
 ### `src/hypernote/sdk.py` or `src/hypernote/errors.py`
 
 - preserve the notebook-first public object model
@@ -155,14 +148,19 @@ Default CLI contract:
   - alternate valid input shapes from upstream payloads
   - parity between real helpers and any fake/test-double implementations
 
+### `pyproject.toml` version, `CHANGELOG.md`, or `.github/workflows/release.yml`
+
+- always use the PR-based release process in [dev/release.md](dev/release.md)
+- do not push release-prep commits directly to master, even for a one-line version bump
+- before opening the release PR, confirm `git ls-tree origin/master` shows every file mentioned in the new CHANGELOG section — local-only work must not be claimed in the changelog
+- if you change the release workflow shape (steps, secrets, version source), update [dev/release.md](dev/release.md) in the same PR so the doc stays accurate
+
 ## Verification
 
 Install guidance:
 
 - `uv sync`
-  - base Hypernote runtime/server usage
-- `uv sync --extra lab`
-  - adds the collaborative JupyterLab bundle
+  - Hypernote's default JupyterLab integration stack
 - `uv sync --extra dev`
   - adds local development, lint, test, and browser-validation tooling
 

{hypernote-0.2.0 → hypernote-0.4.0}/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 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
+collaboration/docprovider stack, `setup serve` opens Lab by default, and
+`setup doctor` can distinguish API reachability from shared-document and Lab
+frontend health.
+
+### Changed
+
+- Hypernote is now packaged and documented as a JupyterLab-first integration:
+  the default install includes JupyterLab collaboration support, `setup serve`
+  opens Lab by default, `setup doctor` reports the shared-document stack and
+  duplicate local servers, and cell-state operations require the shared
+  document path instead of falling back to contents-manager edits.
+
+### Notes
+
+- correction: the 0.2.0 headline mentions "an experimental VS Code extension" but the
+  `vscode-extension/` work was never committed and did not ship in the 0.2.0 artifact.
+  Documentation referring to the VS Code extension has been removed from `README.md`,
+  `AGENTS.md`, `SKILL.md`, `docs/README.md`, `dev/README.md`, and `dev/module-map.md`.
+
 ## 0.2.0 - 2026-05-07
 
 Native JupyterLab as a first-class concurrent actor: open a notebook

hypernote-0.4.0/CONTEXT.md

@@ -0,0 +1,53 @@
+# Hypernote
+
+Hypernote coordinates notebook execution through a Hypernote-enabled JupyterLab
+server so agents and humans can work against one notebook truth.
+
+## Language
+
+**Shared Document**:
+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
+
+**Open Lab Tab**:
+A browser tab viewing a notebook through the Hypernote JupyterLab Server.
+_Avoid_: separate Lab server, plain Lab tab
+
+**Agent Automation**:
+CLI or SDK notebook work performed through the Hypernote JupyterLab Server, whether an Open Lab Tab currently exists.
+_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**.
+
+## Example Dialogue
+
+> **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.2.0 → hypernote-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypernote
-Version: 0.2.0
+Version: 0.4.0
 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
@@ -8,37 +8,37 @@ Project-URL: Issues, https://github.com/gilad-rubin/hypernote/issues
 Requires-Python: >=3.11
 Requires-Dist: click>=8.0
 Requires-Dist: httpx>=0.27
+Requires-Dist: jupyter-collaboration>=3.0
+Requires-Dist: jupyter-docprovider>=2.0
 Requires-Dist: jupyter-server-nbmodel>=0.1
 Requires-Dist: jupyter-server-ydoc>=1.0
 Requires-Dist: jupyter-server>=2.0
+Requires-Dist: jupyterlab>=4.0
 Requires-Dist: pycrdt>=0.12
 Provides-Extra: dev
-Requires-Dist: jupyter-collaboration>=3.0; extra == 'dev'
-Requires-Dist: jupyterlab>=4.0; extra == 'dev'
 Requires-Dist: playwright>=1.40; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
-Provides-Extra: lab
-Requires-Dist: jupyter-collaboration>=3.0; extra == 'lab'
 Description-Content-Type: text/markdown
 
 # Hypernote
 
-- **Notebook-first** - Hypernote is a thin execution control plane on top of Jupyter shared documents.
+- **JupyterLab-first** - Hypernote is a thin execution control plane for a Hypernote-enabled JupyterLab server.
 - **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
 
 - notebook-first SDK in `src/hypernote/sdk.py`
 - agent-first CLI in `src/hypernote/cli/main.py`
 - Jupyter server extension for execution and runtime control
-- experimental VS Code extension in `vscode-extension/` for embedding JupyterLab in VS Code
+- subshell-routed execute, interrupt, and restart so JupyterLab stays usable while Hypernote is running cells
 - notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
-- job polling and `input()` round-trips for headless execution
+- job polling and `input()` round-trips for agent automation without requiring an open Lab tab
 - live-server and browser regression coverage for shared-document behavior
 
 ## Quick start
@@ -56,23 +56,18 @@ uv run hypernote status tmp/demo.ipynb --full
 For another repo's environment, install Hypernote there (`uv add hypernote --dev`) and run
 the same bootstrap command from that repo.
 
-## Install tiers
+## Install
 
-- `hypernote`
-  - core + server + shared-doc runtime
-  - use this for real Hypernote SDK/server usage
-- `hypernote[lab]`
-  - adds the JupyterLab collaboration bundle
-  - use this when you want the full collaborative JupyterLab experience
-- `hypernote[dev]`
-  - adds test, lint, browser, and local dev tooling
-  - use this for local development and CI
+The default install includes the JupyterLab integration stack Hypernote needs:
+JupyterLab, shared-document support, server-side notebook execution, and the
+collaboration/docprovider frontend packages.
+
+Use `hypernote[dev]` only for local development and CI tooling.
 
 Examples:
 
 ```bash
 uv sync
-uv sync --extra lab
 uv sync --extra dev
 ```
 
@@ -82,6 +77,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
 
@@ -105,16 +101,7 @@ Hypernote owns:
 - [CLI Reference](docs/cli.md)
 - [SDK Reference](docs/sdk.md)
 - [Runtime Model](docs/runtime-model.md)
-- [VS Code Extension](docs/vscode-extension.md)
-
-## VS Code
-
-The repository now includes a minimal VS Code extension under `vscode-extension/`.
-
-- It embeds JupyterLab inside a VS Code custom editor or panel.
-- It can reuse an existing Jupyter server via settings.
-- If no server is reachable, it can start a managed local `jupyter lab` process.
-- It stays decoupled from Hypernote-specific UI so Hypernote can connect to the same server separately.
+- [Browser Regression Spec](docs/browser-regression-spec.md)
 
 ## Verification
 
@@ -128,11 +115,3 @@ uv sync --extra dev
 uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```
-
-Extension build:
-
-```bash
-cd vscode-extension
-npm install
-npm run compile
-```

{hypernote-0.2.0 → hypernote-0.4.0}/README.md

@@ -1,18 +1,19 @@
 # Hypernote
 
-- **Notebook-first** - Hypernote is a thin execution control plane on top of Jupyter shared documents.
+- **JupyterLab-first** - Hypernote is a thin execution control plane for a Hypernote-enabled JupyterLab server.
 - **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
 
 - notebook-first SDK in `src/hypernote/sdk.py`
 - agent-first CLI in `src/hypernote/cli/main.py`
 - Jupyter server extension for execution and runtime control
-- experimental VS Code extension in `vscode-extension/` for embedding JupyterLab in VS Code
+- subshell-routed execute, interrupt, and restart so JupyterLab stays usable while Hypernote is running cells
 - notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
-- job polling and `input()` round-trips for headless execution
+- job polling and `input()` round-trips for agent automation without requiring an open Lab tab
 - live-server and browser regression coverage for shared-document behavior
 
 ## Quick start
@@ -30,23 +31,18 @@ uv run hypernote status tmp/demo.ipynb --full
 For another repo's environment, install Hypernote there (`uv add hypernote --dev`) and run
 the same bootstrap command from that repo.
 
-## Install tiers
+## Install
 
-- `hypernote`
-  - core + server + shared-doc runtime
-  - use this for real Hypernote SDK/server usage
-- `hypernote[lab]`
-  - adds the JupyterLab collaboration bundle
-  - use this when you want the full collaborative JupyterLab experience
-- `hypernote[dev]`
-  - adds test, lint, browser, and local dev tooling
-  - use this for local development and CI
+The default install includes the JupyterLab integration stack Hypernote needs:
+JupyterLab, shared-document support, server-side notebook execution, and the
+collaboration/docprovider frontend packages.
+
+Use `hypernote[dev]` only for local development and CI tooling.
 
 Examples:
 
 ```bash
 uv sync
-uv sync --extra lab
 uv sync --extra dev
 ```
 
@@ -56,6 +52,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
 
@@ -79,16 +76,7 @@ Hypernote owns:
 - [CLI Reference](docs/cli.md)
 - [SDK Reference](docs/sdk.md)
 - [Runtime Model](docs/runtime-model.md)
-- [VS Code Extension](docs/vscode-extension.md)
-
-## VS Code
-
-The repository now includes a minimal VS Code extension under `vscode-extension/`.
-
-- It embeds JupyterLab inside a VS Code custom editor or panel.
-- It can reuse an existing Jupyter server via settings.
-- If no server is reachable, it can start a managed local `jupyter lab` process.
-- It stays decoupled from Hypernote-specific UI so Hypernote can connect to the same server separately.
+- [Browser Regression Spec](docs/browser-regression-spec.md)
 
 ## Verification
 
@@ -102,11 +90,3 @@ uv sync --extra dev
 uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```
-
-Extension build:
-
-```bash
-cd vscode-extension
-npm install
-npm run compile
-```