Harden install + notebook flow for the workshop room (council points 1-5)#12
Merged
Conversation
Implements the council's points 1-5 so the per-tool teaching notebooks reliably materialize across OSs and experience levels, and the room runs a reproducible, CI-verified install. 1. Non-destructive fetch_notebooks.py: fetch each tool into a temp dir, require >=1 .ipynb, then atomically swap. A failed/repeated run can no longer shutil.rmtree a working set before the copy — committed copies stay put. 2. Vendor the teaching notebooks: tutorials/<tool>/notebooks/ are now committed (un-gitignored) so they're present on clone; each dir has a PROVENANCE.md (upstream source + license). fetch_notebooks.py becomes an optional refresh. 3. CI gates them: smoke.yml runs fetch_notebooks.py (red build on upstream notebook-CLI drift), and validate_notebooks.py now validates the vendored teaching notebooks too. 4. Cross-platform lock: mark pywinpty win32-only so requirements.lock installs on Linux/macOS; switch CI + docs to install the lock (the room's set). 5. Pre-flight gate: scripts/verify.py self-checks python/ffmpeg/venv/tool versions/kernel/notebooks/data with PASS/FAIL + fix hints; ORGANIZER.md adds the "verify before the room" email gate + a cross-OS dry-run checklist. Docs aligned (README, INSTALL, ORGANIZER, per-tool READMEs): lock is the recommended install, kernel registration added to the quick start, notebooks documented as committed + optionally refreshed, verify.py added as a step. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…stall error A participant on the wrong Python hit "No matching distribution found for camap[notebook]" — camap caps at <3.14 and needs >=3.11, so 3.14 (newest) and 3.10 both fail. Document the exact symptom and point at verify.py. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
We're 3 days out and install instructions ship tomorrow, so this prioritizes a reproducible, CI-verified install and guarantees the per-tool teaching notebooks are present — implementing points 1–5 from the install-friction council review.
Changes
1 · Non-destructive
fetch_notebooks.py— fetches each tool into a temp dir, requires ≥1.ipynb, then atomically swaps. The old code didshutil.rmtree(dest)before the copy, so a failed re-run (flaky wifi, upstream drift) destroyed a working set. Now a failure leaves the committed copy untouched and exits loud.2 · Teaching notebooks are vendored/committed —
tutorials/<tool>/notebooks/is un-gitignored and the 9 known-good notebooks (minisim ×4, minian ×3, eztrack ×2) are committed, so they're present on clone. Each dir gets aPROVENANCE.md(upstream source + GPL license + refresh note).fetch_notebooks.pybecomes an optional, version-matched refresh.3 · CI gates the notebooks —
smoke.ymlnow runsfetch_notebooks.py(a red build the moment an upstream notebook-CLI drifts), andvalidate_notebooks.pyvalidates the vendored teaching notebooks instead of skipping them.4 · Cross-platform lock —
pywinptymarked; sys_platform == "win32"sorequirements.lockinstalls on Linux/macOS. CI now installs the lock (the set the room runs), not the unpinnedrequirements.txt.5 · Pre-flight gate — new
scripts/verify.pyself-checks Python / ffmpeg / venv / tool versions / kernel / notebooks / data withPASS/FAIL+ exact fix commands.ORGANIZER.mdadds the "run verify before the room" email gate and a cross-OS clean-machine dry-run checklist (the lock is CI-verified on Linux but untested on macOS/ARM — that dry run is the real cross-OS guarantee).Docs aligned — README/INSTALL/ORGANIZER + per-tool READMEs: lock is the recommended install, kernel registration added to the quick start (it was missing), notebooks documented as committed + optionally refreshed,
verify.pyadded as a step.Verification
validate_notebooks.pypasses on all 13 committed notebooks locally.verify.pyruns clean (ASCII output, Windows-safe).fetch_notebooks.py(all 3 tools), data fetch, capstone execution.Not in this PR (flagged for the organizer)
🤖 Generated with Claude Code