hypernote 0.1.3__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.3 → hypernote-0.2.0}/AGENTS.md

@@ -6,6 +6,7 @@ Notebook-first execution system built on top of Jupyter shared documents
 
 ```bash
 uv sync --extra dev
+uv run hypernote
 uv run hypernote --help
 uv run hypernote setup serve
 uv run hypernote setup doctor
@@ -13,7 +14,7 @@ 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 hypernote tests
+uv run ruff check src/hypernote tests
 ```
 
 ## Architecture
@@ -27,20 +28,23 @@ Jupyter owns notebook truth:
 
 Hypernote owns a thin control plane:
 
-- public SDK in [hypernote/sdk.py](hypernote/sdk.py)
-- public errors in [hypernote/errors.py](hypernote/errors.py)
-- agent-first CLI in [hypernote/cli/main.py](hypernote/cli/main.py)
-- execution orchestration and shared-document mutation in [hypernote/execution_orchestrator.py](hypernote/execution_orchestrator.py)
-- runtime ownership in [hypernote/runtime_manager.py](hypernote/runtime_manager.py)
-- HTTP handlers in [hypernote/server/handlers.py](hypernote/server/handlers.py)
-- Jupyter extension wiring in [hypernote/server/extension.py](hypernote/server/extension.py)
-- ephemeral job and attribution ledger in [hypernote/actor_ledger.py](hypernote/actor_ledger.py)
+- 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
@@ -52,6 +56,7 @@ Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb`
 
 ### CLI
 
+- `hypernote` — live workspace dashboard with hints
 - `create`
 - `ix`
 - `exec`
@@ -70,9 +75,11 @@ Lifecycle rule: notebook contents and outputs persist through Jupyter's `.ipynb`
 
 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
@@ -81,12 +88,16 @@ Default CLI contract:
 
 - 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/`.
 
@@ -106,20 +117,24 @@ Default CLI contract:
 - update [docs/vscode-extension.md](docs/vscode-extension.md)
 - update [dev/vscode-extension.md](dev/vscode-extension.md)
 
-### `hypernote/sdk.py` or `hypernote/errors.py`
+### `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)
 
-### `hypernote/cli/main.py`
+### `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)
 
-### `hypernote/execution_orchestrator.py`, `hypernote/runtime_manager.py`, or `hypernote/server/*`
+### `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
@@ -134,6 +149,11 @@ Default CLI contract:
   - 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
 
@@ -149,7 +169,7 @@ Install guidance:
 Minimum checks for most changes:
 
 ```bash
-uv run ruff check hypernote tests
+uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```
 
@@ -159,3 +179,10 @@ When browser or live-server behavior changes, also use:
 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.1.3 → hypernote-0.2.0}/CHANGELOG.md

@@ -4,15 +4,29 @@ 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
 
-- added a minimal VS Code extension under `vscode-extension/` that opens JupyterLab in a VS Code custom editor or panel
-- added managed local JupyterLab startup for the extension when no configured server is reachable
+- 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
 
-- the extension is intentionally decoupled from Hypernote-specific UI and connects to plain JupyterLab
-- managed extension launches override Jupyter's default frame-ancestor policy so the embedded view can load inside VS Code
+- 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
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypernote
-Version: 0.1.3
+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,8 +33,8 @@ 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
@@ -92,6 +92,13 @@ 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](docs/getting-started.md)
@@ -118,7 +125,7 @@ uv sync --extra dev
 ```
 
 ```bash
-uv run ruff check hypernote tests
+uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```
 

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

@@ -7,8 +7,8 @@
 
 ## 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
@@ -66,6 +66,13 @@ 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](docs/getting-started.md)
@@ -92,7 +99,7 @@ uv sync --extra dev
 ```
 
 ```bash
-uv run ruff check hypernote tests
+uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```
 

{hypernote-0.1.3 → hypernote-0.2.0}/SKILL.md

@@ -7,7 +7,11 @@ description: Work against Hypernote's notebook-first SDK and agent-first CLI. Us
 
 `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 --help` for the current command list, and `uv run hypernote <command> --help` for exact syntax.
+Design rule: if a compact read model, truncation rule, or focused observation flow is useful in the CLI and also generally useful to agents or other adapters, define it in the SDK first and let the CLI render it, rather than re-encoding the logic in the CLI.
+
+Review rule: prefer finishing a feature with contract cleanup, not just feature coverage. Variants should share one envelope, aggregate names should match their exact semantics, and adapters should normalize boundary payload shapes instead of assuming one representation.
+
+Run `uv run hypernote` for a live workspace dashboard, `uv run hypernote --help` for the current command list, and `uv run hypernote <command> --help` for exact syntax.
 
 ## Prerequisite
 
@@ -63,6 +67,7 @@ uv run hypernote --server http://127.0.0.1:8889 setup doctor
 ## Quick Start
 
 ```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 create tmp/demo.ipynb --empty
@@ -112,14 +117,15 @@ Do not use `-s` for multi-line code. Shell quoting will corrupt newlines.
 - `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
+- `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. Fix the source with `edit replace`.
-3. Re-run with `exec <cell-id>`.
-4. Continue with the next `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`.
+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.
 
@@ -140,12 +146,17 @@ know exactly where to resume. Cells after the halt point were never inserted int
 4. Prefer the SDK and CLI over raw HTTP unless you are explicitly working on server routes.
 5. Treat Jupyter shared documents as the source of truth. Open or closed JupyterLab tabs must not change correctness.
 6. For agents, prefer default non-TTY JSON output unless you intentionally want background streaming.
-7. Use `--stream-json` only when you plan to watch the process; otherwise it wastes context.
-8. Start the server with `hypernote setup serve` instead of hand-writing Jupyter flags.
-9. Skip large rich outputs such as `graph.visualize()` in headless automation unless the visualization is the point of the run.
-10. Use unique notebook paths in tests and demos.
-11. Move durable notes into `docs/` or `dev/`; keep `tmp/` disposable.
-12. Treat Hypernote jobs, runtime state, and cell attribution as ephemeral coordination state, not durable history.
+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.
+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.
+14. When changing read/inspection behavior, update the SDK observation helpers before or alongside the CLI so every adapter shares the same summary/truncation rules.
+15. Keep command hints grounded in shipped commands and actual runtime values. Do not document or suggest a focused read flag unless it exists in the CLI.
+16. For contract-heavy changes, test the focused variants, empty/failure states, and alternate valid payload shapes, not just the happy path.
+17. When a helper moves into the SDK or another shared layer, remove the old CLI/test copy in the same change.
 
 ## Before You Change Behavior
 
@@ -167,6 +178,6 @@ Use `uv sync` for base runtime work and `uv sync --extra lab` when you specifica
 Then run:
 
 ```bash
-uv run ruff check hypernote tests
+uv run ruff check src/hypernote tests
 uv run python -m pytest -q
 ```

hypernote-0.2.0/dev/README.md

@@ -0,0 +1,29 @@
+# Development Docs
+
+This folder is internal reference for the shipped Hypernote architecture.
+
+Public workflow docs live in `docs/`. This folder is for implementation-facing notes only.
+
+Read these first:
+
+- [Current Architecture](current-architecture.md)
+- [Module Map](module-map.md)
+- [Testing and Verification](testing-and-verification.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)
+
+Rules:
+
+- keep this folder small
+- document shipped behavior, not aspirational redesigns
+- when behavior changes, update `AGENTS.md`, `SKILL.md`, `docs/`, and `dev/` together
+- prefer one short source of truth per principle instead of repeating long process notes across many docs
+- use this folder for implementation discipline and architecture notes; keep public contract wording in `docs/`
+- for cross-surface changes, write down the invariants that must stay true across variants, not just the happy-path workflow

hypernote-0.2.0/dev/cli-agent-ergonomics-rollout.md

@@ -0,0 +1,69 @@
+# CLI Agent Ergonomics Rollout
+
+This document tracks the AXI-inspired improvements for Hypernote's CLI.
+
+Status:
+
+- Phase 1 is shipped and documented in the public CLI reference.
+- Phase 2 and Phase 3 remain open.
+
+Goals:
+
+- reduce agent discovery turns
+- keep default non-TTY reads compact
+- make notebook state easier to act on without extra calls
+- preserve JSON compatibility and the existing SDK-first CLI contract
+
+Non-goals for now:
+
+- replacing JSON with a custom format
+- shell hook ambient context
+- changing all error output conventions at once
+
+## Phase 1 Shipped
+
+- [x] Add contextual `hint:` lines after high-value commands.
+- [x] Make bare `hypernote` show a live home view instead of help text.
+- [x] Add precomputed notebook aggregates to `status`.
+- [x] Redesign default `cat` output to be summary-first.
+- [x] Truncate large outputs by default in agent-oriented reads.
+- [x] Add focused read flags for notebook inspection.
+- [x] Make empty states explicit across notebook, runtime, and job reads.
+
+Shipped behavior:
+
+- `hypernote` with no subcommand returns actionable live state instead of Click help
+- `status` answers "is this notebook healthy?" from top-level fields
+- `cat` answers "what cells are here and which one should I inspect?" without full dumps
+- large outputs are truncated in non-TTY reads unless `--full-output` is used
+- hints only reference shipped commands and real runtime values
+- the compact read model is now SDK-backed so the CLI is not the only place that knows the summary/truncation rules
+
+## Remaining Backlog
+
+### Phase 2
+
+- [ ] Add a one-command repair path for failed cells.
+- [ ] Add richer recovery hints for failed, timed out, and awaiting-input jobs.
+- [ ] Make `job get` and `runtime status` summary-first.
+- [ ] Make `setup doctor` more decision-oriented.
+- [ ] Flatten agent-oriented JSON output where it helps avoid deep nesting.
+
+### Phase 3
+
+- [ ] Add `--fields` support on read commands.
+- [ ] Normalize `--full`, `--full-output`, and `--max-output` semantics.
+- [ ] Add stable machine-readable error codes for JSON mode.
+- [ ] Shorten subcommand help and make it example-led.
+- [ ] Add concrete command examples to help output.
+- [ ] Keep responses content-first and help-second.
+- [ ] Include notebook-relative context in hints where possible.
+- [ ] Consider a dedicated `home` or `dashboard` command if the bare root becomes overloaded.
+- [ ] Consider optional ambient context hooks after core command outputs are strong.
+- [ ] Add richer notebook health summaries for stale or mismatched runtime states.
+
+## Deferred
+
+- TOON or other custom output formats
+- shell/session hook ambient context
+- sweeping stdout/stderr contract changes