Fix 1.1 release audit findings and complete documentation follow-ups

.claude/CLAUDE.md

@@ -13,4 +13,22 @@
 - **2026-09-05** A 'clean' docs build (sphinx -W -E -a) does NOT remove sphinx-gallery's generated docs/auto_examples/ (gitignored): after deleting or renaming an example, rm -rf docs/auto_examples first or -W fails on 'document isn't included in any toctree' for the stale pages (2026-09-05, after the gallery consolidation). <!-- id:n391712600x317 -->
 - **2026-09-05** Subagent dispatch prompts must state the no-mocks rule verbatim ('no mock objects, no monkeypatching library functions as spies; prove behaviour with real observables'): on 2026-09-05 an agent verified 'never touches the network' by monkeypatching requests.get and seaborn_dataset; replaced with mtime/.part/uncached-URL-raises observables. <!-- id:n4091109334x348 -->
 - **2026-09-05** Never assert absolute font-metric numbers (probe heights, figure inches, pixel rows) in tests: CI's matplotlib (3.11.1) hints text differently from the local 3.10.8 -- 2026-09-05 two new tests failed on every CI job while green locally; assert against the library's own probe on the same axes, or relative tolerances. <!-- id:n1698690037x325 -->
+- **2026-09-06** A test that compares repo-relative paths as strings (allowlists, rosters, planted-marker findings) must build them with os.path.relpath(...).replace(os.sep, '/'): on 2026-09-06 the widened examples scanner passed on macOS/Linux and failed all four Windows jobs on 'docs\tutorials\align.ipynb' vs 'docs/tutorials/align'. <!-- id:n3130054099x327 -->
+- **2026-09-06** os.replace onto a file other threads are reading/renaming raises PermissionError (WinError 5) on Windows only; wrap cache/atomic-write renames in a short retry that accepts an existing identical destination (hypertools/io/sources.py _replace_retrying, 2026-09-06), and expect Windows CI to be the only place such a test fails. <!-- id:n2929415745x334 -->
+- **2026-09-06** A release verification pipeline (notebook re-execution -> full pytest -> sphinx -W gallery -> example smoke gate) runs ~50 min, past the 10-min Bash cap: write it as a scratchpad zsh script with step markers, launch with nohup, and poll the log for the DONE marker from run_in_background watchers (each <=9.5 min); git checkout the two autosummary stubs FrameContext/LSLStream after any sphinx build (whitespace-regenerated). <!-- id:n3762867048x433 -->
+- **2026-09-06** A line whose markers are drawn on a SEPARATE artist (fmt split, truth= overlay) shows a marker-less legend glyph; keep marker= on the line artist with markevery=[] so the legend handle carries it -- fixed twice (45fe7799 fmt split; truth overlay 2026-09-06), so check every marker-splitting draw path for this. <!-- id:n1685346725x318 -->
+- **2026-09-06** The gitignored Colab feature tour (notes/colab/hypertools_1.1_feature_tour.ipynb) is prose that goes stale exactly like docs/tutorials: two 2026-09-06 findings (9.8 'plotly panels drop return_model', 12.4 'pip install predict-hf first') were library behaviours already fixed on-demand; include notes/colab/*.ipynb in the post-change grep of note n2056000368x385, and verify an install claim in a FRESH venv (python -m venv + pip install . + the call) before editing it. <!-- id:n3699028289x477 -->
+- **2026-09-07** pkill -f <pipeline.sh> kills only the zsh script; its running child (pytest, sphinx) is orphaned and keeps going, so relaunching the pipeline ran TWO sphinx builds whose 'rm -rf docs/auto_examples' deleted each other's files (2026-09-07: FileNotFoundError on auto_examples/animate_weather_decades.py, scraper 'did not produce expected image'); kill the children too (pkill -f 'm sphinx -W'; pkill -f 'pytest -q') and confirm with ps before relaunching. <!-- id:n3738080889x460 -->
+- **2026-09-07** Plotly sizes a 3-D scene by its domain HEIGHT only and clips at the sides (measured 2026-09-07: same 267x209 px cube in 600x300 and 1200x300 scenes; a 300x600 scene's cube is 415 tall, cut at 300 wide): at hypertools' default eye the cube is 0.89 x height wide, 0.70 tall, and apparent size ~ 1/eye-distance only when backing OFF (an eye nearer than ~0.8x clips the front). Name a calibration constant by its reference (SCENE_CUBE_WIDTH_PER_HEIGHT was 1.4 = width per CUBE height, read as width per SCENE height, so every square panel cell backed the camera off 1.4x). <!-- id:n1370451665x576 -->
+- **2026-09-07** Figure QA that works (2026-09-07, Jeremy's design): three SEPARATED agents -- one writes each figure's EXPECTED appearance from the notebook code/prose + docstrings without seeing images, one describes the OBSERVED renders without seeing code, one adjudicates with probes -- found 11 real gaps in the tour that solo eyeballing missed (ax= palette ignored, z-label outside the tight bbox, 2-D frame on the data, faded recoloured forecasts); render plotly outputs from their notebook JSON with kaleido (scratchpad review/manifest + tour_out/extract.py pattern) and re-run only the changed figures per round. <!-- id:n1781868848x613 -->
+- **2026-09-07** sed 's/a/b/' without the g flag replaces only the FIRST match per line: deriving full_verify4.sh from full_verify3.sh by 's/sphinx_err2/sphinx_err4/' redirected sphinx stderr to the new file but left the same line's grep -c counting the STALE old file, so two pipelines reported 'warnings 1' on clean builds (2026-09-07); use /g (or a variable for the path) when a line names a file twice. <!-- id:n1233963273x397 -->
+- **2026-09-07** Forecast index != dataset index: a predict=[...] collection's forecasts are MODEL-MAJOR (forecast i = model i//n_datasets, dataset i%n_datasets), and hue=/cluster= regrouping makes RUN index != dataset index. Three round-3/4 findings (2026-09-07) were the same confusion: static ownership skipped when counts coincided, animated reveal lookups by forecast index (IndexError), plotly hyp_dataset tags. Any new code that touches a forecast must translate through _model_forecast_owner / forecast_datasets (forecast -> source dataset) and _forecast_owner / _seg_ds (dataset -> final run) before indexing schedules, lines or runs. <!-- id:n1598193450x634 -->
+- **2026-09-07** An LSL test that resolves by type='EEG' fails whenever ANOTHER process advertises an idle EEG outlet (2026-09-07: a VS Code notebook kernel with the tutorial's synthetic outlet, and a Codex audit executing the same notebook) because lsl_stream() takes the first match; give a test outlet a unique stream TYPE (like the unique names) and check pylsl.resolve_streams() for foreign outlets before blaming the library. <!-- id:n2334423855x422 -->
+- **2026-09-08** Never git stash in a tree other agents are editing: on 2026-09-08 a subagent stashed to compare a baseline and unstaged every other agent's index (recovered via git read-tree from the stash's index commit); compare against HEAD with git show HEAD:<path> or a scratch copy instead. <!-- id:n970508101x288 -->
+- **2026-09-08** A process-global setting that is both a direct call and a context manager (hyp.set_autoinstall) took three red-team rounds to get right (restore-order race, retained handles, construct-then-enter race across threads): model it as LIVE handle records (weakrefs, construction order) plus a BASELINE folded in by the weakref callback of a handle that dies unentered, take the newer of top-record and baseline by call order, mark exited records finished; test overlapping blocks across threads, construct-then-enter interleaving, 100k discarded direct calls (tracemalloc), and a block handle dying after exit. <!-- id:n1244798541x613 -->
+- **2026-09-08** Codex exec rounds die at the account usage limit with NO -o report (twice on 2026-09-08, ~200k tokens each): salvage findings from the stdout log (grep for MAJOR/MINOR headings), and write the next prompt to skip the gallery build/notebook re-runs and to APPEND findings to the notes file as it goes; the slim prompt finished in 10 minutes. <!-- id:n859586284x348 -->
+- **2026-09-08** The repo's readme is lowercase 'readme.md': a test that opens 'README.md' passes on macOS (case-insensitive) and fails on every Linux CI job (2026-09-08, tests/test_format_data.py); grep the tracked filename with git ls-files before hard-coding a path in a test. <!-- id:n162227783x270 -->
+- **2026-09-08** A watcher that greps a codex run log for the cut-off phrase ('usage limit') exits at once because codex echoes the PROMPT into the log and the prompt mentions the usage limit (2026-09-08, two wasted watcher cycles); grep the server's own wording ('hit your usage limit', 'Try again at') and never a phrase the prompt contains. <!-- id:n1274548565x334 -->
+- **2026-09-11** Agent isolation:'worktree' can base the new worktree on origin's default branch (master @ 96ac8b7f) instead of the current branch HEAD (2 of 8 fixers on 2026-09-11), and fails outright when the shell cwd is outside the repo; cd to the repo first and make every worktree prompt check 'git log -1' and reset to the intended base before editing. <!-- id:n2445035275x350 -->
+- **2026-09-11** Colab and Kaggle auto-select the PLOTLY render backend, so any code using a matplotlib-only return API (fig.axes, .canvas, HyperAnimation .draw_frame/.on_frame/.n_frames, an internal hyp.plot call) breaks there while passing locally: seen 3x on 2026-09-11 (plot_stream's head plot, tour ANIM-clock/PLOT-cjk, five launch notebooks). Pin backend='matplotlib' at such call sites and test them under hyp.set_interactive_backend('plotly'), the same preference Colab sets. <!-- id:n2896508265x474 -->
 <!-- skillnote:end -->

.github/workflows/test.yml

@@ -108,6 +108,12 @@ jobs:
         # wheels for all three CI platforms/Python versions here.
         pip install -e ".[dev,torch]"
 
+    - name: Check repository lint (Ubuntu Python 3.12)
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+      run: |
+        python -m pip install "ruff==0.15.20"
+        python -m ruff check .
+
     - name: Pre-fetch headless Chrome for kaleido (Plotly image/GIF export)
       # tests/test_animation_export.py exports Plotly figures to GIF/MP4 via
       # kaleido 1.x, which drives a headless Chrome. Pre-fetching it here (into
@@ -289,6 +295,18 @@ jobs:
       run: |
         cd /tmp/docs-clean/docs
         python -m sphinx -b html -W -E -a . _build/html
+    - name: Run the docstring and guide examples (sphinx doctest builder)
+      env:
+        MPLBACKEND: Agg
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        # the gallery was just built; the doctest builder only needs the
+        # `>>>` examples in docstrings and the guides (release audit
+        # 2026-09-07: two `hypertools.load` examples failed under this
+        # builder while the HTML build was green)
+        HYPERTOOLS_DOCS_PLOT_GALLERY: '0'
+      run: |
+        cd /tmp/docs-clean/docs
+        python -m sphinx -b doctest -W . _build/doctest
     - name: Release gate -- generated gallery notebooks install the PyPI package
       # docs/auto_examples/*.ipynb are gitignored and GENERATED by the build
       # above from docs/conf.py's branch-aware install-cell (so they don't exist