hypernote 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -0,0 +1,161 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g., 0.1.3)"
+        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
+
+permissions:
+  contents: write
+
+jobs:
+  validate-inputs:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.validate.outputs.version }}
+    steps:
+      - name: Validate version format
+        id: validate
+        run: |
+          VERSION="${{ inputs.version }}"
+          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.1.3, 0.2.0-alpha.1)"
+            exit 1
+          fi
+          echo "✅ Version format is valid"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+  release:
+    needs: validate-inputs
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version_update.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: Update version and create commit
+        id: version_update
+        env:
+          VERSION: ${{ needs.validate-inputs.outputs.version }}
+        run: |
+          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
+
+          echo "✅ Version updated to $VERSION"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          if ! git diff --quiet pyproject.toml; then
+            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"
+          fi
+
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        env:
+          VERSION: ${{ steps.version_update.outputs.version }}
+        run: |
+          TAG="v$VERSION"
+          if git tag -l | grep -q "^$TAG$"; then
+            git tag -d "$TAG" || true
+            git push origin ":refs/tags/$TAG" || true
+          fi
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+          echo "✅ Created and pushed tag $TAG"
+
+      - 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-${{ steps.version_update.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 GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="v${{ steps.version_update.outputs.version }}"
+          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 \
+              ${{ inputs.create_draft && '--draft' || '' }}
+          fi
+
+      - name: Summary
+        run: |
+          echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "- **Version:** v${{ steps.version_update.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **PyPI:** ${{ inputs.publish_to_pypi }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Draft:** ${{ inputs.create_draft }}" >> $GITHUB_STEP_SUMMARY
+
+  publish-pypi:
+    needs: release
+    if: ${{ inputs.publish_to_pypi }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist-${{ needs.release.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.1.2 → hypernote-0.2.0}/.gitignore

@@ -18,3 +18,4 @@ lib/
 .jupyter/
 .agent-repl/
 tmp/
+vscode-extension/out/

hypernote-0.2.0/AGENTS.md

@@ -0,0 +1,188 @@
+# Hypernote
+
+Notebook-first execution system built on top of Jupyter shared documents
+
+## Quick Start
+
+```bash
+uv sync --extra dev
+uv run hypernote
+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
+uv run python -m pytest -q
+uv run ruff check src/hypernote tests
+```
+
+## Architecture
+
+Jupyter owns notebook truth:
+
+- `.ipynb` persistence
+- shared YDoc document state
+- kernel and session primitives
+- notebook rendering in JupyterLab
+
+Hypernote owns a thin control plane:
+
+- public SDK in [src/hypernote/sdk.py](src/hypernote/sdk.py)
+- public errors in [src/hypernote/errors.py](src/hypernote/errors.py)
+- agent-first CLI in [src/hypernote/cli/main.py](src/hypernote/cli/main.py)
+- execution orchestration and shared-document mutation in [src/hypernote/execution_orchestrator.py](src/hypernote/execution_orchestrator.py)
+- runtime ownership in [src/hypernote/runtime_manager.py](src/hypernote/runtime_manager.py)
+- HTTP handlers in [src/hypernote/server/handlers.py](src/hypernote/server/handlers.py)
+- 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.
+
+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.
+
+## Shipped Surface
+
+### SDK
+
+- `hypernote.connect(path, create=False)`
+- `Notebook`, `CellCollection`, `CellHandle`, `Runtime`, `Job`
+- `nb.run(...)`, `nb.run_all()`, `nb.restart()`, `nb.interrupt()`
+- `nb.snapshot()`, `nb.status()`, `nb.diff(...)`
+
+### CLI
+
+- `hypernote` — live workspace dashboard with hints
+- `create`
+- `ix`
+- `exec`
+- `edit`
+- `run-all`
+- `restart`
+- `restart-run-all`
+- `interrupt`
+- `status`
+- `diff`
+- `cat`
+- `job ...`
+- `runtime ...`
+- `setup doctor`
+- `setup serve`
+
+Default CLI contract:
+
+- bare `hypernote` shows live workspace state and next-step hints
+- TTY: concise human-readable progress
+- 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 doctor --path PATH` is the preferred first diagnostic when server reachability,
+  kernelspec selection, or runtime mismatch is unclear
+
+## Rules
+
+- Terminology: when the user says "our system", treat that as the maintained project-operating surface, including `AGENTS.md`, `SKILL.md`, `docs/`, `dev/`, tests, and other shared guidance or verification artifacts around the code.
+- SDK first. CLI behavior should come from the SDK, not duplicate raw HTTP semantics.
+- When CLI and SDK both need compact observation behavior, define the summary/truncation/focused-read logic in the SDK and let the CLI adapt it.
+- Shared logic needs one owner. When a helper or shaping rule moves into the SDK or another shared layer, delete the old copies instead of letting multiple versions drift.
+- One truth. Do not reintroduce a contents-vs-YDoc split for notebook reads or writes.
+- Runtime creation must honor the requested kernel first, otherwise notebook metadata
+  `kernelspec.name`, otherwise `python3`.
+- Keep control-plane state ephemeral. Do not add durable job history unless the product explicitly needs it.
+- Our system is part of done. After every meaningful change, update the relevant parts of `AGENTS.md`, `SKILL.md`, `docs/`, `dev/`, tests, and adjacent shared project guidance so they stay in sync with implementation.
+- Keep adapters thin. CLI, JupyterLab, and tests should reuse shared contracts instead of re-encoding notebook behavior.
+- Treat output and API shapes as contracts. Feature variants should preserve the same top-level envelope and field semantics unless there is a deliberate, documented exception.
+- 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/`.
+
+## Read These First
+
+- [SKILL.md](SKILL.md)
+- [docs/README.md](docs/README.md)
+- [dev/README.md](dev/README.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
+- keep public enums and errors stable
+- prefer adding reusable observation helpers on `NotebookStatus` / `CellStatus` over adding CLI-only shaping logic
+- update [docs/sdk.md](docs/sdk.md)
+
+### `src/hypernote/cli/main.py`
+
+- keep non-TTY output compact by default
+- keep bare `hypernote` as the live dashboard view
+- preserve `ix` as the happy-path command
+- preserve summary-first `status` and compact `cat` with contextual hints
+- prefer rendering SDK observation helpers over introducing new CLI-only data shaping
+- keep streaming explicit in non-TTY mode
+- update [docs/cli.md](docs/cli.md)
+
+### `src/hypernote/execution_orchestrator.py`, `src/hypernote/runtime_manager.py`, or `src/hypernote/server/*`
+
+- preserve the single-truth shared-document path
+- verify open-tab and late-open behavior still hold
+- update [dev/current-architecture.md](dev/current-architecture.md)
+- if browser-visible behavior changes, update [docs/browser-regression-spec.md](docs/browser-regression-spec.md)
+
+### `tests/*`
+
+- prefer the narrowest test that proves the behavior
+- preserve coverage for:
+  - SDK shape
+  - CLI output contract
+  - live server behavior
+  - browser regression for streaming and late-open correctness
+- for contract-heavy changes, add invariant coverage for:
+  - default and focused variants
+  - empty and failure states
+  - alternate valid input shapes from upstream payloads
+  - parity between real helpers and any fake/test-double implementations
+
+## Verification
+
+Install guidance:
+
+- `uv sync`
+  - base Hypernote runtime/server usage
+- `uv sync --extra lab`
+  - adds the collaborative JupyterLab bundle
+- `uv sync --extra dev`
+  - adds local development, lint, test, and browser-validation tooling
+
+Minimum checks for most changes:
+
+```bash
+uv run ruff check src/hypernote tests
+uv run python -m pytest -q
+```
+
+When browser or live-server behavior changes, also use:
+
+```bash
+HYPERNOTE_INTEGRATION=1 uv run python -m pytest -q tests/test_live_server.py
+uv run python -m pytest -q tests/test_browser_regression.py
+```
+
+Before opening or updating a PR for a cross-surface change, do a short contract pass:
+
+- check that sibling command variants still share one consistent envelope
+- check that aggregate field names still match their exact semantics
+- check that docs and hints only mention shipped commands and flags
+- check that moved logic no longer has stale copies in adapters or tests

hypernote-0.2.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.2.0 - 2026-05-07
+
+Native JupyterLab as a first-class concurrent actor: open a notebook
+mid-run and see streaming output, click Stop and the cell terminates,
+click Restart and the kernel comes back ready. Plus the package now ships
+in PyPA src layout and an experimental VS Code extension.
+
+### Added
+
+- subshell-routed kernel execution (JEP 91 / ipykernel 7+): Hypernote sends `execute_request` with a `subshell_id` so the kernel's main shell stays free to answer concurrent clients (e.g. JupyterLab) — opening a notebook mid-run now renders cells immediately and continues to stream output without waiting for the running cell
+- subshell-aware `POST /api/kernels/{id}/interrupt` override: JupyterLab's Stop button (and `nb.interrupt()`) now terminates a Hypernote-driven cell, raising `KeyboardInterrupt` in the subshell thread via a main-shell `PyThreadState_SetAsyncExc` injection. Falls back to default SIGINT for non-Hypernote-driven kernels.
+- subshell- and nbmodel-aware `POST /api/kernels/{id}/restart` override: JupyterLab's Restart button now leaves the kernel ready to run new cells. Hypernote evicts nbmodel's stale per-kernel client and worker, and clears its cached subshell id, so the next execute rebuilds against the fresh kernel.
+- new browser regression tests for Lab Stop and Lab Restart against subshell-routed cells; new real-kernel unit tests for subshell creation, routing, interrupt latency, and restart cleanup.
+
+### Changed
+
+- package layout migrated to `src/hypernote/` (PyPA src layout). `pyproject.toml` now configures `[tool.hatch.build.targets.wheel] packages = ["src/hypernote"]` and `[tool.ruff] src = ["src", "tests"]`. The `hypernote` import name is unchanged — `import hypernote` continues to work.
+- release workflow switched from tag-triggered to `workflow_dispatch` — run `gh workflow run release.yml -f version=X.Y.Z` to release
+
+### Notes
+
+- subshell routing requires ipykernel 7+ (IPython kernels). Other kernels fall back to the main shell — late-open during a long-running cell will block the JupyterLab UI for those kernels and the subshell-targeted interrupt becomes a no-op (override falls through to SIGINT, which works on the main shell).
+- `PyThreadState_SetAsyncExc`-based interrupt cannot terminate a thread inside a long blocking C call without GIL release (e.g. `requests.get` with no timeout). The `KeyboardInterrupt` only fires once control returns to Python. The interrupt snippet falls back to `os.kill(pid, SIGINT)` internally if the subshell thread cannot be found, so user-visible "Stop did nothing" cases degrade to default SIGINT behavior rather than silent failure.
+
+## 0.1.3 - 2026-04-03
+
+Cross-repo runtime hardening and agent ergonomics.
+
+### Added
+
+- `hypernote setup serve` — bootstraps a Hypernote-enabled Jupyter server with all required extensions
+- `hypernote setup doctor --path PATH` — reports notebook kernelspec, live runtime kernel, resolved launcher, and warns on mismatches
+- `hypernote create --empty` — removes any default cells Jupyter auto-inserts so notebooks start clean
+- batch `ix` output now includes `cells_inserted`, `cells_total`, `cells_remaining`, `halt_reason`, and `last_processed_cell_id` on early halt
+- timeout errors now surface job id, last known status, and recovery hints pointing to `job get` and `cat`
+- runtime kernel mismatch detection — clear error when a live runtime's kernel doesn't match notebook metadata, with guidance to restart
+
+### Changed
+
+- execution now resolves kernels as: explicit override > notebook metadata `kernelspec.name` > `python3`
+- `RuntimeManager.ensure_room()` rejects silent reuse when a live room exists with a different kernel name
+- removed all hardcoded local paths from project markdown files — links are now repo-relative
+- SKILL.md rewritten: iterative `ix → observe → ix` is the primary workflow, heredoc/stdin documented for multi-line cells, server lifecycle section added, cross-repo setup simplified to `uv add hypernote --dev`
+
+### Notes
+
+- `--cells-file` batch mode is now documented as a convenience for known-good sequences, not the default workflow
+- the recommended cross-repo pattern is now: install hypernote in the target repo, not `uv run --with`
+
+## 0.1.1 - 2026-04-02
+
+Patch release focused on release automation hardening.
+
+### Changed
+
+- updated the GitHub release workflow to newer official action majors where available
+- replaced the third-party GitHub release action with the `gh` CLI in release automation
+- fixed the release workflow to install Playwright browser binaries before running browser tests
+- fixed the release workflow to run tests with the `dev` extra installed
+- fixed the PyPI publish step to use token-only `uv publish` authentication
+
+### Notes
+
+- package code is unchanged from `0.1.0`
+- this release exists to verify and stabilize the automated release path
+
+## 0.1.0 - 2026-04-02
+
+Initial public release.
+
+### Added
+
+- notebook-first Python SDK built around `Notebook`, `CellCollection`, `CellHandle`, `Runtime`, and `Job`
+- agent-first CLI with `create`, `ix`, `exec`, `edit`, `run-all`, `restart`, `interrupt`, `status`, `diff`, `cat`, `job`, and `runtime` flows
+- Jupyter server extension with narrow Hypernote REST handlers
+- notebook-scoped runtime lifecycle with attach, detach, recovery, stop, and GC
+- headless execution flow over Jupyter shared documents and `jupyter-server-nbmodel`
+- job polling and `input()` round-trip support for long-running or interactive execution
+- live-server and browser regression tests for late-open, persistence, and shared-document correctness
+- project and developer docs for the runtime model, SDK, CLI, and release workflow
+
+### Changed
+
+- aligned the control plane around an explicitly ephemeral lifecycle
+- moved job tracking and cell attribution to an in-memory notebook-scoped ledger
+- removed the SQLite dependency and any implied durable job history
+
+### Notes
+
+- Jupyter owns durable notebook contents and outputs in `.ipynb`
+- Hypernote owns ephemeral runtime state, jobs, and attribution

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypernote
-Version: 0.1.2
+Version: 0.2.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
@@ -33,9 +33,10 @@ Description-Content-Type: text/markdown
 
 ## What it ships
 
-- notebook-first SDK in `hypernote/sdk.py`
-- agent-first CLI in `hypernote/cli/main.py`
+- 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
 - notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
 - job polling and `input()` round-trips for headless execution
 - live-server and browser regression coverage for shared-document behavior
@@ -45,11 +46,16 @@ 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
 ```
 
+For another repo's environment, install Hypernote there (`uv add hypernote --dev`) and run
+the same bootstrap command from that repo.
+
 ## Install tiers
 
 - `hypernote`
@@ -86,12 +92,29 @@ Hypernote owns:
 - actor attribution
 - SDK, CLI, and thin REST handlers
 
+## Design 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
+- adapters should normalize valid upstream shape differences at the boundary
+- tests should cover invariants across variants, not only the main workflow
+
 ## Documentation
 
-- [Getting Started](/Users/giladrubin/python_workspace/hypernote/docs/getting-started.md)
-- [CLI Reference](/Users/giladrubin/python_workspace/hypernote/docs/cli.md)
-- [SDK Reference](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md)
-- [Runtime Model](/Users/giladrubin/python_workspace/hypernote/docs/runtime-model.md)
+- [Getting Started](docs/getting-started.md)
+- [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.
 
 ## Verification
 
@@ -102,6 +125,14 @@ uv sync --extra dev
 ```
 
 ```bash
-uv run ruff check hypernote tests
+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.1.2 → hypernote-0.2.0}/README.md

@@ -7,9 +7,10 @@
 
 ## What it ships
 
-- notebook-first SDK in `hypernote/sdk.py`
-- agent-first CLI in `hypernote/cli/main.py`
+- 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
 - notebook-scoped runtime lifecycle with attach, detach, recovery, and stop
 - job polling and `input()` round-trips for headless execution
 - live-server and browser regression coverage for shared-document behavior
@@ -19,11 +20,16 @@
 ```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
 ```
 
+For another repo's environment, install Hypernote there (`uv add hypernote --dev`) and run
+the same bootstrap command from that repo.
+
 ## Install tiers
 
 - `hypernote`
@@ -60,12 +66,29 @@ Hypernote owns:
 - actor attribution
 - SDK, CLI, and thin REST handlers
 
+## Design 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
+- adapters should normalize valid upstream shape differences at the boundary
+- tests should cover invariants across variants, not only the main workflow
+
 ## Documentation
 
-- [Getting Started](/Users/giladrubin/python_workspace/hypernote/docs/getting-started.md)
-- [CLI Reference](/Users/giladrubin/python_workspace/hypernote/docs/cli.md)
-- [SDK Reference](/Users/giladrubin/python_workspace/hypernote/docs/sdk.md)
-- [Runtime Model](/Users/giladrubin/python_workspace/hypernote/docs/runtime-model.md)
+- [Getting Started](docs/getting-started.md)
+- [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.
 
 ## Verification
 
@@ -76,6 +99,14 @@ uv sync --extra dev
 ```
 
 ```bash
-uv run ruff check hypernote tests
+uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```
+
+Extension build:
+
+```bash
+cd vscode-extension
+npm install
+npm run compile
+```