Summary
Add a Jupyter notebook version of the 5-minute tutorial (docs/tutorial.md) that runs top-to-bottom in Google Colab from a fresh environment, with an "Open in Colab" badge in the README.
Why this matters
A notebook is the lowest-friction first-run experience: no clone, no venv, no editor — pip install weaver-kernel in cell one and a working capability grant by cell three. For a security library whose value is best understood by seeing a denial and an audit trace happen, an interactive walkthrough converts curiosity into comprehension faster than any README.
Proposed scope
examples/notebooks/tutorial.ipynb: mirrors the tutorial flow (register → grant → invoke → deny → expand → explain), each step with a short markdown cell explaining what just happened and which invariant it demonstrates.- First cell:
%pip install weaver-kernel + setting WEAVER_KERNEL_SECRET (with a note about what that secret is).
- A deliberate
PolicyDenied cell showing the structured denial explanation, and a final cell printing the full audit trail.
- README badge ("Open in Colab") next to the tutorial link.
- CI execution via
jupyter nbconvert --execute (or nbclient) in the docs/test job so the notebook can't drift from the API — same philosophy as the CI-executed README quickstart.
Implementation notes
- Async: notebooks have a running event loop; use
await kernel.invoke(...) directly (top-level await works in IPython) rather than asyncio.run() — worth a one-line callout since it differs from the script examples.
- Keep outputs stripped in git (pre-commit or
nbstripout guidance in CONTRIBUTING) so diffs stay reviewable; CI re-executes to validate.
- Pin nothing in the notebook; it should track the released package (
pip install weaver-kernel) but CI should execute it against the working tree (editable install) to catch breakage before release.
Acceptance criteria
Out of scope
- Multiple notebooks (one excellent tutorial first; federation/firewall deep-dives can follow).
- Binder/JupyterLite hosting.
References
- In-repo:
docs/tutorial.md, examples/tutorial.py, tests/test_readme_quickstart.py (docs-can't-drift pattern).
Priority: P2 · Effort: S · Impact: Medium
Summary
Add a Jupyter notebook version of the 5-minute tutorial (
docs/tutorial.md) that runs top-to-bottom in Google Colab from a fresh environment, with an "Open in Colab" badge in the README.Why this matters
A notebook is the lowest-friction first-run experience: no clone, no venv, no editor —
pip install weaver-kernelin cell one and a working capability grant by cell three. For a security library whose value is best understood by seeing a denial and an audit trace happen, an interactive walkthrough converts curiosity into comprehension faster than any README.Proposed scope
examples/notebooks/tutorial.ipynb: mirrors the tutorial flow (register → grant → invoke → deny → expand → explain), each step with a short markdown cell explaining what just happened and which invariant it demonstrates.%pip install weaver-kernel+ settingWEAVER_KERNEL_SECRET(with a note about what that secret is).PolicyDeniedcell showing the structured denial explanation, and a final cell printing the full audit trail.jupyter nbconvert --execute(ornbclient) in the docs/test job so the notebook can't drift from the API — same philosophy as the CI-executed README quickstart.Implementation notes
await kernel.invoke(...)directly (top-level await works in IPython) rather thanasyncio.run()— worth a one-line callout since it differs from the script examples.nbstripoutguidance in CONTRIBUTING) so diffs stay reviewable; CI re-executes to validate.pip install weaver-kernel) but CI should execute it against the working tree (editable install) to catch breakage before release.Acceptance criteria
Out of scope
References
docs/tutorial.md,examples/tutorial.py,tests/test_readme_quickstart.py(docs-can't-drift pattern).Priority: P2 · Effort: S · Impact: Medium