Fix 1.1 release audit findings and complete documentation follow-ups

.claude/CLAUDE.md

@@ -1,16 +0,0 @@
-<!-- skillnote:begin -->
-## Notes (skill-compounder)
-
-- **2026-09-03** Executing a docs/tutorials launch notebook locally runs its Colab '%pip install ... git+...@dev-1.0' cell, which overwrites the venv's editable hypertools with the stale REMOTE branch mid-run (seen 2026-09-03 as '48 dimensions ... static plots support at most 2'). scripts/execute_tutorial.py now tags 'pip install' cells skip-execution in memory; after any other notebook run, check 'pip show hypertools' says Editable, and 'pip install -e .[dev]' if not. <!-- id:n4007036607x464 -->
-- **2026-09-03** Regenerating a docs/tutorials notebook from its example script (Plan 4 pattern, used 5x on 2026-09-03): generate cells from the script's section markers with a scratchpad script (install cell carried over byte-identical), never leave a HyperAnimation as a cell's last expression (its repr embeds an 89 KB video), execute with scripts/execute_tutorial.py (skips pip-install cells, disables HF progress bars), save the GIF at <=15 fps / ~300 frames (a 900-frame GIF is 13 MB), record the measured visible-output set in tests/test_examples_are_native.py, re-measure the budget once, commit script+notebook+GIF+gate together. Gallery pages for show=False examples need the HyperAnimation scraper in docs/conf.py. <!-- id:n2702453330x716 -->
-- **2026-09-03** When a push will trigger hosted CI, commit the session-note/memory update BEFORE the push (seen twice on 2026-09-03: note committed right after each push, so every CI cycle had to be re-run or cancelled on the note-only head; PR #283). <!-- id:n2368342412x243 -->
-- **2026-09-03** Bluesky launch thread (notes/bluesky-launch, gitignored): re-verify atproto lexicon limits with curl before posting (video cap moved 100->300 MB between July and Sept 2026), count post graphemes with the regex module's \X (not len), render clips from the examples' construct_artifact() via the scratchpad render script, and expect tutorial 'Full code' links to 404 until RTD builds master. <!-- id:n1333699239x397 -->
-- **2026-09-03** Yahoo v8 chart 'range=max&interval=1d' silently returns 3-MONTH bars (AAPL: 169 rows since 1984); pass explicit period1/period2 epoch bounds to get daily. SEC XBRL needs a User-Agent with a contact (the project's pyproject email); 'companyconcept' can be EMPTY for a filer (ABT, KO) whose 'companyfacts' has the concept (measured 2026-09-03). <!-- id:n1509545511x350 -->
-- **2026-09-03** Tutorial notebooks are GENERATED (scripts/generate_tutorial_notebook.py) then executed (scripts/execute_tutorial.py); after changing SPECS (dpi, prose) ALWAYS regenerate before re-executing -- on 2026-09-04 a dpi revert was made in the generator only, and two 10-minute re-executions wrote the stale dpi. Video size is CRF-bound now (was a fixed 1800 kbit/s), so dpi does not trade size. <!-- id:n1221150995x395 -->
-- **2026-09-04** After a library behaviour change (new error text, a warning removed, a new return type), grep docs/tutorials/*.ipynb for prose or stored outputs demonstrating the OLD behaviour and re-execute those notebooks (2026-09-04: io.ipynb taught hyp.load(df) as a TypeError after load gained passthrough; align/reduce stored the glyph warning; lsl_streaming stored the liblsl ERR line). <!-- id:n2056000368x385 -->
-- **2026-09-05** When the finding IS that a file/match is absent, chain ls/grep with '|| true' (or test -e) so the expected exit 1 is not logged as a tool failure <!-- id:n3078545694x153 lesson:c1376737082x187-e1648091495x17 -->
-- **2026-09-05** Guard sed -n "$((n-12)),..." on a possibly-empty $n: an empty grep result makes sed see '-12' as an option; use grep -B/-A context instead <!-- id:n708886190x146 lesson:c662557965x199-e2303256208x40 -->
-- **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 -->
-<!-- skillnote:end -->

.claude/compound/lessons/bluesky-launch-thread/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: bluesky-launch-thread
+description: Use when preparing or posting the Bluesky launch thread (notes/bluesky-launch, gitignored).
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Re-verify atproto lexicon limits with curl before posting (the video cap has moved, 100 to
+300 MB). Count post graphemes with the regex module's \X, not len. Render clips from the
+examples' construct_artifact() via the scratchpad render script. Expect tutorial "Full
+code" links to 404 until Read the Docs builds master.

.claude/compound/lessons/commit-notes-before-push/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: commit-notes-before-push
+description: Use when about to push a branch that triggers hosted CI and a session-note or memory update is still uncommitted.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Commit the session-note or memory update BEFORE the push. A note committed right after the
+push moves the head to a note-only commit, and every CI cycle has to be re-run or cancelled.

.claude/compound/lessons/datatype-gate-no-raw-isinstance/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: datatype-gate-no-raw-isinstance
+description: Use when writing or delegating hypertools library code that checks whether an input is a DataFrame, Series or array.
+created: 2026-10-09
+origin: project hypertools, session f69d921d
+---
+Classify inputs with the shared helpers in hypertools/_shared/helpers.py
+(is_frame_dataset, is_series_like, is_array_dataset, as_pandas_dataframe), never with
+`isinstance(x, pd.DataFrame)` or `isinstance(x, pd.Series)`. tests/test_datatype_gate.py
+scans the package and fails with "datatype check(s) outside the shared coercion layer"
+for each raw check, so polars and other frames are treated like pandas ones.
+An agent's targeted test run usually does not include that file, and the failure then
+shows up only in the full suite: put `tests/test_datatype_gate.py` in the test list of
+any prompt that adds input handling. To tell a row-labelled pandas Series from a polars
+one, use `is_series_like(x)` plus a non-callable `x.index`.

.claude/compound/lessons/docs-site-check-every-page/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: docs-site-check-every-page
+description: Use when asked to build the hypertools Sphinx / Read the Docs site and confirm it looks correct, or when reviewing built docs pages in a browser.
+created: 2026-10-09
+origin: project hypertools, session f69d921d
+---
+Check EVERY built page with a scripted browser, never a hand-picked list. Build the RTD
+way (from docs/: READTHEDOCS=True READTHEDOCS_GIT_IDENTIFIER=master READTHEDOCS_OUTPUT=$OUT
+sphinx -T -b html -d _build/doctrees . $OUT/html, then python docs/post_build.py), serve
+$OUT/html with `python -m http.server`, and run check_built_site.py (beside this lesson;
+playwright is in .venv; see also scripts/verify_docs_playwright.py). It reads each page's
+::before/::after content for ERROR/WARNING, broken images, console errors, leaked RST and
+overflow at 1400px and 400px, and saves screenshots to look at.
+Why: a sampled review passed the site while docs/hierarchy.html showed furo's red
+"ERROR: Adding a table of contents" box from a `.. contents::` directive. That box is CSS
+::before text, so sphinx -W (0 warnings), HTML text scans and link checkers cannot see it.
+Before trusting 0 findings, plant a defect on a temporary copy of a page and confirm the
+checker reports it.

.claude/compound/lessons/docs-site-check-every-page/check_built_site.py

@@ -0,0 +1,97 @@
+import json
+import os
+import sys
+from playwright.sync_api import sync_playwright
+
+# usage: python check_built_site.py HTML_DIR BASE_URL OUT_DIR   (serve HTML_DIR first: python -m http.server)
+ROOT = sys.argv[1]
+BASE = sys.argv[2].rstrip("/") + "/"
+OUT = sys.argv[3]
+os.makedirs(OUT, exist_ok=True)
+pages = sorted(
+    os.path.relpath(os.path.join(d, f), ROOT)
+    for d, _, fs in os.walk(ROOT)
+    for f in fs
+    if f.endswith(".html") and not d.startswith(os.path.join(ROOT, "_"))
+)
+shots = [
+    p
+    for p in pages
+    if (
+        ("/" not in p and not p.startswith("hypertools."))
+        or p.startswith("tutorials/")
+        or p == "auto_examples/index.html"
+    )
+]
+shots += [
+    "hypertools.plot.html",
+    "hypertools.predict.html",
+    "hypertools.describe.html",
+    "hypertools.io.LSLStream.html",
+    "hypertools.HyperAnimation.html",
+]
+JS = """() => {
+  const out={};
+  out.broken=[...document.images].filter(i=>i.complete&&i.naturalWidth===0).map(i=>i.getAttribute('src')).slice(0,5);
+  out.overflow=document.documentElement.scrollWidth-document.documentElement.clientWidth;
+  const pseudo=[]; for(const el of document.querySelectorAll('article *')){ for(const ps of ['::before','::after']){ const c=getComputedStyle(el,ps).content; if(c&&/ERROR|WARNING|unnecessary/i.test(c)) pseudo.push(el.tagName+'.'+el.className+': '+c.slice(0,80)); } }
+  out.pseudo=pseudo.slice(0,3);
+  out.sysmsg=document.querySelectorAll('.system-message, .problematic').length;
+  out.videos=[...document.querySelectorAll('video')].length;
+  const txt=[...document.querySelectorAll('article p, article li, article dd, article dt, article h1, article h2, article h3')].map(e=>{const c=e.cloneNode(true); c.querySelectorAll('code,pre,.math,script,style').forEach(x=>x.remove()); return c.textContent;}).join('\\n');
+  out.leaks=(txt.match(/[^\\n]{0,30}(``|:[a-z]+:`|\\.\\. [a-z-]+::)[^\\n]{0,30}/g)||[]).slice(0,3);
+  return out; }"""
+res = {}
+with sync_playwright() as pw:
+    b = pw.chromium.launch()
+    for theme in ["light"]:
+        ctx = b.new_context(viewport={"width": 1400, "height": 1800})
+        pg = ctx.new_page()
+        errs = []
+        pg.on(
+            "console",
+            lambda m: errs.append(m.text[:160]) if m.type == "error" else None,
+        )
+        pg.on("pageerror", lambda e: errs.append("PAGEERROR " + str(e)[:160]))
+        for p in pages:
+            errs.clear()
+            try:
+                pg.goto(BASE + p, wait_until="load", timeout=60000)
+                pg.wait_for_timeout(400)
+            except Exception as e:
+                res[p] = {"goto": str(e)[:100]}
+                continue
+            r = pg.evaluate(JS)
+            r["console"] = sorted(set(errs))[:4]
+            res[p] = r
+            if p in shots:
+                pg.screenshot(path=os.path.join(OUT, p.replace("/", "__") + ".png"))
+    # phone width overflow on every page
+    ctx = b.new_context(viewport={"width": 400, "height": 800})
+    pg = ctx.new_page()
+    for p in pages:
+        try:
+            pg.goto(BASE + p, wait_until="load", timeout=60000)
+            pg.wait_for_timeout(250)
+            res[p]["phone_overflow"] = pg.evaluate(
+                "()=>document.documentElement.scrollWidth-document.documentElement.clientWidth"
+            )
+        except Exception as e:
+            res[p]["phone"] = str(e)[:80]
+    b.close()
+json.dump(res, open(os.path.join(OUT, "results.json"), "w"), indent=1)
+bad = {
+    p: r
+    for p, r in res.items()
+    if r.get("broken")
+    or r.get("overflow", 0) > 2
+    or r.get("pseudo")
+    or r.get("sysmsg")
+    or r.get("leaks")
+    or r.get("console")
+    or r.get("phone_overflow", 0) > 2
+    or "goto" in r
+}
+print(len(res), "pages checked;", len(bad), "with findings")
+for p, r in bad.items():
+    print(p, {k: v for k, v in r.items() if v and k not in ("videos",)})

.claude/compound/lessons/figure-qa-three-separated-agents/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: figure-qa-three-separated-agents
+description: Use when reviewing the figures of a hypertools notebook or the feature tour for correctness.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Use three SEPARATED agents: one writes each figure's EXPECTED appearance from the notebook
+code, prose and docstrings without seeing images; one describes the OBSERVED renders
+without seeing code; one adjudicates with probes. This finds gaps solo eyeballing misses
+(ax= palette ignored, z-label outside the tight bbox, a 2-D frame on the data, faded
+recoloured forecasts). Render plotly outputs from their notebook JSON with kaleido (the
+scratchpad review/manifest and tour_out/extract.py pattern), and re-run only the changed
+figures each round.

.claude/compound/lessons/forecast-index-is-not-dataset-index/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: forecast-index-is-not-dataset-index
+description: Use when writing hypertools code that indexes schedules, lines or runs by a forecast.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+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. Any 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. The bug hides when the counts coincide
+and shows as an IndexError in animated reveal lookups or wrong plotly hyp_dataset tags.

.claude/compound/lessons/global-setting-as-context-manager/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: global-setting-as-context-manager
+description: Use when changing hyp.set_autoinstall or adding another process-global setting that is both a direct call and a context manager.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Model it as LIVE handle records (weakrefs, in construction order) plus a BASELINE folded
+in by the weakref callback of a handle that dies unentered; take the newer of the top
+record and the baseline by call order; mark exited records finished. The failure modes are
+a restore-order race, retained handles, and a construct-then-enter race across threads.
+Test overlapping blocks across threads, construct-then-enter interleaving, 100k discarded
+direct calls (tracemalloc), and a block handle dying after exit.

.claude/compound/lessons/legend-marker-on-line-artist/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: legend-marker-on-line-artist
+description: Use when a hypertools draw path puts a line's markers on a separate artist (fmt split, truth= overlay).
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+A line whose markers are drawn on a SEPARATE artist shows a marker-less legend glyph. Keep
+marker= on the line artist with markevery=[] so the legend handle carries it, and check
+every marker-splitting draw path for this.

.claude/compound/lessons/lsl-test-unique-stream-type/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: lsl-test-unique-stream-type
+description: Use when writing or debugging a hypertools LSL test that resolves a stream by type.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+A test that resolves by type='EEG' fails whenever ANOTHER process advertises an idle EEG
+outlet (a notebook kernel running the tutorial's synthetic outlet), because lsl_stream()
+takes the first match. Give a test outlet a unique stream TYPE, as with the unique names,
+and check pylsl.resolve_streams() for foreign outlets before blaming the library.

.claude/compound/lessons/no-absolute-font-metrics-in-tests/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: no-absolute-font-metrics-in-tests
+description: Use when writing a hypertools test that asserts text or figure measurements.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Never assert absolute font-metric numbers (probe heights, figure inches, pixel rows). CI's
+matplotlib (3.11.1) hints text differently from the local 3.10.8, so such tests pass
+locally and fail on every CI job. Assert against the library's own probe on the same axes,
+or use relative tolerances.

.claude/compound/lessons/notebook-pip-cell-overwrites-editable/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: notebook-pip-cell-overwrites-editable
+description: Use when executing a docs/tutorials notebook locally in hypertools.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+A launch notebook's Colab cell `%pip install ... git+...@dev-1.0` overwrites the venv's
+editable hypertools with the stale REMOTE branch mid-run (symptom: "48 dimensions ...
+static plots support at most 2"). Execute with scripts/execute_tutorial.py, which tags
+'pip install' cells skip-execution in memory. After any other notebook run, check that
+`pip show hypertools` says Editable, and run `pip install -e .[dev]` if not.

.claude/compound/lessons/pin-matplotlib-backend-for-colab/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: pin-matplotlib-backend-for-colab
+description: Use when hypertools code or a notebook uses a matplotlib-only return API (fig.axes, .canvas, HyperAnimation .draw_frame/.on_frame/.n_frames, an internal hyp.plot call).
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Colab and Kaggle auto-select the PLOTLY render backend, so matplotlib-only return APIs
+break there while passing locally (plot_stream's head plot, the tour's animation clock,
+launch notebooks). Pin backend='matplotlib' at such call sites and test them under
+hyp.set_interactive_backend('plotly'), the same preference Colab sets.

.claude/compound/lessons/plotly-scene-sized-by-height/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: plotly-scene-sized-by-height
+description: Use when sizing or calibrating a Plotly 3-D scene or its camera distance in hypertools.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Plotly sizes a 3-D scene by its domain HEIGHT only and clips at the sides: the same
+267x209 px cube appears in 600x300 and 1200x300 scenes, and a 300x600 scene's cube is 415
+tall, cut at 300 wide. At hypertools' default eye the cube is 0.89 x height wide and 0.70
+x height tall, and apparent size goes as 1/eye-distance only when backing OFF (an eye
+nearer than about 0.8x clips the front). Name a calibration constant by its reference:
+SCENE_CUBE_WIDTH_PER_HEIGHT = 1.4 means width per CUBE height, and reading it as width per
+SCENE height backs the camera off 1.4x in every square panel cell.

.claude/compound/lessons/readme-is-lowercase/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: readme-is-lowercase
+description: Use when a hypertools test or script opens the repository readme by path.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+The repository's readme is lowercase `readme.md`. A test that opens 'README.md' passes on
+macOS (case-insensitive) and fails on every Linux CI job. Check the tracked file name with
+`git ls-files` before hard-coding a path in a test.

.claude/compound/lessons/regenerate-before-reexecute/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: regenerate-before-reexecute
+description: Use when changing SPECS (dpi, prose) for the generated tutorial notebooks in hypertools.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+Tutorial notebooks are GENERATED (scripts/generate_tutorial_notebook.py) and then executed
+(scripts/execute_tutorial.py). After changing SPECS, ALWAYS regenerate before
+re-executing; otherwise a 10-minute re-execution writes the stale value. Video size is
+CRF-bound (not a fixed bitrate), so dpi does not trade against size.

.claude/compound/lessons/regenerate-tutorial-notebook/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: regenerate-tutorial-notebook
+description: Use when regenerating a docs/tutorials notebook from its example script in hypertools.
+created: 2026-10-03
+origin: notes kept in CLAUDE.md
+---
+1. Generate cells from the script's section markers with a scratchpad script; carry the
+   install cell over byte-identical.
+2. Never leave a HyperAnimation as a cell's last expression (its repr embeds an 89 KB video).
+3. Execute with scripts/execute_tutorial.py (skips pip-install cells, disables HF progress bars).
+4. Save the GIF at <=15 fps and about 300 frames (a 900-frame GIF is 13 MB).
+5. Record the measured visible-output set in tests/test_examples_are_native.py and
+   re-measure the budget once.
+6. Commit script, notebook and GIF and the gate together.
+Gallery pages for show=False examples need the HyperAnimation scraper in docs/conf.py.