hypernote 0.2.0__tar.gz → 0.3.0__tar.gz

hypernote-0.3.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.3.0}/AGENTS.md

@@ -37,7 +37,6 @@ 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.
 
@@ -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.3.0}/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 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.3.0/CONTEXT.md

@@ -0,0 +1,38 @@
+# 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
+
+**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**.
+- 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**."
+
+## 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**.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypernote
-Version: 0.2.0
+Version: 0.3.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,25 +8,24 @@ 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.
@@ -36,9 +35,9 @@ Description-Content-Type: text/markdown
 - 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 +55,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
 ```
 
@@ -105,16 +99,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 +113,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.3.0}/README.md

@@ -1,6 +1,6 @@
 # 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.
@@ -10,9 +10,9 @@
 - 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 +30,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
 ```
 
@@ -79,16 +74,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 +88,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.3.0}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 headlessly, inspect notebook status or diffs, or verify JupyterLab attach/streaming behavior.
+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
@@ -23,7 +23,7 @@ Hypernote CLI requires two things:
    uv add hypernote --dev
    ```
 
-2. **A running Jupyter server with the Hypernote extension enabled.**
+2. **A running Hypernote-enabled JupyterLab server.**
    See "Server lifecycle" below.
 
 Once both are in place, all commands are just `uv run hypernote ...`.
@@ -44,11 +44,12 @@ Verify it points to your repo's `.venv/bin/python`. If it does, the server is go
 **If no server is running, start one in the background:**
 
 ```bash
-uv run hypernote setup serve &
+uv run hypernote setup serve --no-browser &
 ```
 
 `setup serve` is a foreground process — run it in the background so your terminal stays
-available. The default address is `http://127.0.0.1:8888`.
+available. The default address is `http://127.0.0.1:8888`. Omit `--no-browser`
+when you want setup to open JupyterLab immediately.
 
 **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`
@@ -60,7 +61,7 @@ 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 &
+uv run hypernote setup serve --port 8889 --no-browser &
 uv run hypernote --server http://127.0.0.1:8889 setup doctor
 ```
 
@@ -69,7 +70,7 @@ uv run hypernote --server http://127.0.0.1:8889 setup doctor
 ```bash
 uv run hypernote                   # live workspace dashboard and hints
 uv run hypernote setup doctor            # check for existing server
-uv run hypernote setup serve &           # only if no server is running
+uv run hypernote setup serve --no-browser &  # only if no server is running
 uv run hypernote create tmp/demo.ipynb --empty
 uv run hypernote ix tmp/demo.ipynb -s 'value = 20 + 22'
 uv run hypernote status tmp/demo.ipynb --full
@@ -149,7 +150,7 @@ know exactly where to resume. Cells after the halt point were never inserted int
 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 headless automation unless the visualization is the point of the run.
+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 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.
@@ -163,7 +164,6 @@ know exactly where to resume. Cells after the halt point were never inserted int
 1. Read [AGENTS.md](AGENTS.md).
 2. Check the current public surface in [docs/cli.md](docs/cli.md) and [docs/sdk.md](docs/sdk.md).
 3. If browser-visible execution behavior changes, check [docs/browser-regression-spec.md](docs/browser-regression-spec.md).
-4. If the VS Code embedding experience changes, check [docs/vscode-extension.md](docs/vscode-extension.md).
 
 ## Verification
 
@@ -173,7 +173,7 @@ Install the right tier first:
 uv sync --extra dev
 ```
 
-Use `uv sync` for base runtime work and `uv sync --extra lab` when you specifically need the full collaborative JupyterLab bundle without the rest of the dev toolchain.
+Use `uv sync` for Hypernote's default JupyterLab integration stack.
 
 Then run:
 

{hypernote-0.2.0 → hypernote-0.3.0}/dev/README.md

@@ -9,15 +9,13 @@ Read these first:
 - [Current Architecture](current-architecture.md)
 - [Module Map](module-map.md)
 - [Testing and Verification](testing-and-verification.md)
+- [Release Process](release.md)
 - [CLI Agent Ergonomics Rollout](cli-agent-ergonomics-rollout.md)
-- [VS Code Extension Notes](vscode-extension.md)
 
-Release path:
-
-- trigger the release workflow from GitHub Actions UI or `gh workflow run release.yml -f version=X.Y.Z`
-- the workflow bumps `pyproject.toml`, syncs `uv.lock`, commits, tags, builds, tests, creates a GitHub release, and publishes to PyPI
-- PyPI auth comes from the GitHub Actions secret `PYPI_API_TOKEN`
-- see [release.yml](../.github/workflows/release.yml)
+Releases: see [Release Process](release.md). Always via PR — release-prep
+commits go through review like feature work. Workflow lives at
+[`.github/workflows/release.yml`](../.github/workflows/release.yml); PyPI
+auth via the `PYPI_API_TOKEN` GitHub Actions secret.
 
 Rules:
 

{hypernote-0.2.0 → hypernote-0.3.0}/dev/current-architecture.md

@@ -18,10 +18,12 @@ Jupyter shared document + kernel/session primitives
 
 - The SDK is the public semantic center.
 - The CLI is a thin shell over the SDK.
-- `setup serve` is the CLI bootstrap path for starting a local Hypernote-enabled Jupyter server.
+- `setup serve` is the CLI bootstrap path for starting a local Hypernote-enabled JupyterLab server.
 - Notebook reads and writes must go through the shared-document path.
 - Execution must resolve cell source from the same document model the UI sees.
-- JupyterLab is an optional viewer/actor, not a second source of truth.
+- JupyterLab is the supported integration environment. Opening a Lab tab is optional,
+  but Hypernote still runs through the Hypernote-enabled JupyterLab server and shared
+  document path.
 
 ## Important consequences