Changelog
All notable changes to this repository. The format follows Keep a Changelog;
phases refer to spec §12 (sitemap-and-content-directory.md).
[Unreleased] — Phase 5 begins: the eegloop core (2026-09-20)
Phase 5 — neurofeedback and BCI on consumer headsets — is proposed in
site/notes/proposal-phase5-consumer-nf-bci.md and gates on eight author decisions listed there.
The library’s synthetic and replay paths gate on none of them, so the library starts first.
Added
loop/eegloop0.1.0, the core. A second installable package besidepipelines/eegpipe, built the same way and deliberately not part of it:eegpipeis a batch pipeline that depends on MNE; this is a loop over blocks of a stream that depends on numpy and scipy. It ports the real-time section ofnotebooks/_shared/helpers_l7.py— ring buffer, causal FIR with state carried across blocks, the latency budget, the loopback probe — into something installable, multichannel and unit-tested (47 tests, no network, no device). The notebook helpers are not edited; a parity test holds the two to 1e-12, and under CI that import is hard so the guard cannot skip itself away.- Two rules the design review forced into the step contract. Quality runs first, on the raw
block, because a gate placed after the band-pass cannot see line noise, muscle or a flat channel —
the chain would otherwise build L7.5’s “the notch deletes the diagnostic” into its own fixed order.
And latency is summed only where it is exact: a linear-phase FIR’s
(N − 1)/2is a row in the budget; a smoother’s delay is not one number and is listed as measured, filled by the probe, never added into the total. - A
libraryCI job mirroring thepipelinesone, with a step that fails if the parity test was skipped. - The spec amendment that makes Phase 5 real (author decisions of 2026-09-20): §12 gains Phase 5;
§6 gains L7.10–L7.16 with
L7.9kept reserved for §13 item 23; §7 gainspath-consumer-nf-bci; §0 rule 6 and §10.6 now admit the author’s own consumer recordings for this track under conditions — a registry entry, a licence, a public home and a consent statement (§13 item 25) — with theIN_HOUSEblock staying until all four exist; §13 items 3, 16 and 23 answered, items 25–27 added.site/CONTRACTS.mdgains the Phase 5 addendum: ownership, the six device-naming rules, the datasets clause, and the rule that no live output is ever an answer key. loop/recordings/is gitignored: the author’s own headset recordings exercise the device path in development and never enter the repository, an asset, or a page (§10.6).- Phase B: sources and steps. (The proposal’s
ScheduledMarkersshipped asListMarkers;KeyboardMarkersfollows in the post-approval fixes.) A synthetic stream with planted answers — alpha bursts, frontal blinks, a dropped-sample gap that shows in the timestamps, clock drift, a flicker component, cues with an evoked response and a lateralised power change, electrode pops, a flat channel — and atruthdict naming every one; replay of arrays,.npz,.csv, the site’s own.bin+sidecar assets and MNE formats, paced on the wall clock or fast, never straddling a gap; cues on the source clock. The quality gate runs first, on the raw block, withdetectors.py’s criteria cited, and a three-state verdict with a hold; reference, frozen spatial filters, envelopes and features each say whether their delay is exact or measured. 83 tests, no network, no device. - Phase C: the neurofeedback loop, the protocol, the session, the command line. Lesson L7.3’s
five decisions are five objects —
SignalSpec(what the signal is, exactly; it writes the sentence CRED-nf item 4 asks for),FixedBaseline/AdaptiveBaseline(each with a note on what it does to a learning claim),ContinuousMapping/ThresholdReward,ShamPolicy(the four modeshelpers_l7names, sealed into the log as a token only the seed unblinds; yoked replays a donor session block for block) — andFeedbackLoopruns them with the display frozen or zeroed on a gated block, never fed a cleaned guess, and the processing row of the budget measured rather than stated. AProtocolfile names every decision and is validated all at once ineegpipe’s message format;SessionLogwritessession.json,events.jsonl,signal.npzandprotocol-resolved.jsonwith every string scrubbed of absolute paths, andSessionReaderopens them with numpy alone;Recorderwrites the stream in spec §4.5’s.bin+sidecar so a learner’s recording opens exactly as a shipped asset does, its sidecar markedlicense: private.eegloop run | validate | budget | probe | versions; two shipped protocols (synthetic; the latency widget’s own eyes-closed trace);examples/alpha_bar.pyas the smallest application.analysis.learning_testis a sign-flip permutation test across sessions besidenaive_trend,helpers_l7.within_session_trendkept and labelled invalid;crednf_reportmarks each of the six items satisfied, not satisfiable alone, or unsatisfied, with why. 113 tests, no network, no device. - Phase D: the BCI loop — calibrate once, freeze, apply.
cut_epochsandEpochCuttercut the same window to the sample, offline and online, on a stated clock (sampleortimestamps), and drop — never patch — an epoch over a gap or a gated stretch.fit_frozenfitscsp_lda,riemann_tsorxdawn_lda(scikit-learn pipelines mirroringhelpers_l7’s families; CSP through pyriemann so thedecodeextra needs no MNE, a stated divergence) with folds in cue order, never shuffled, prints the chance band (chance_interval=helpers_l6.chance_band, held by a parity test), then freezes the pipeline into arrays — spatial filters, tangent-space reference, scaler, classifier — that replay it in numpy to 1e-6, checked before returning;FrozenDecoder.savewrites an.npzwith nothing pickled and the loop runs the arrays.StreamingPosterior+DwellDecision(sliding) and a cue-locked mode,BCILoopwalking calibrate → fit → apply and scoring decisions against the cues it can see;SSVEPDetectorby canonical correlation. Abciblock in the protocol; two shipped protocols (imagery on the planted lateralised alpha, an oddball on the planted P300);examples/cue_switch.py. On the synthetic answers: imagery decodes at 100 % offline and ≥ 85 % online after a temporal split, the four-channel P300 at AUC ≈ 0.7, and CCA finds the planted 12 and 15 Hz flickers. 127 tests, no network, no device. - Two things the synthetic stream made measurable, kept as lessons. The stream’s timestamps
run 200 ppm fast against its sample clock while its cues are on the sample clock, so a cutter that
aligns by timestamps lands the last epoch five samples early — the first parity test failed on
exactly that, and
EpochCutternow takes the clock as a parameter and a test asserts the shift. And the standing 10 Hz alpha correlates with a 10 Hz reference in every window, flicker or not, so an SSVEP detector at an alpha-band frequency reports alpha;SSVEP_NOTEsays so where the detector is described. - Phase F, started: L7.10 and L7.11 as drafts (
content-L7c,notebooks-L7c,data-p5,integrator). L7.10 What a four-channel headband measures withnb-7-10-headband(the two geometries as facts from the board table; the nearest cap sites to TP9/TP10 computed, not asserted — T9/T10, then TP7/TP8; the occipitotemporal replica on twelveds-eegbcisubjects, 12/12 with an eyes-closed alpha peak; the bandwidth edge measured; an on-device notch measured as a loss of diagnostics; the survives-which-geometry matrix). L7.11 Getting a stream withnb-7-11-stream(one interface for replay, synthetic and device; the block contract; the rate measured against the rate claimed; a planted loss counted and verified to the sample; drift in milliseconds; a session recorded in the site’s own format and read back). L7.12 Signal quality you can act on live withnb-7-12-quality(the gate’s criteria cited; sensitivity on planted blinks 27/27, pops, a flat channel and a mains line; three states and a hold; the replica’s unusable fraction, median 0.053 with one popping subject at 1.000, printed as a table; the online gate against the offline detector on the same minute, 11 of 18 blinks; one consumer export’s edge, hole andEQ.*columns by range request; ICA at rank 4 and 64 measured — and the lesson rewritten to say what the numbers say). Three new pitfalls:pf-contact-is-not-signalandpf-adaptive-threshold-moving-target(figures frommake_figures_p5.py, synthetic and labelled so) andpf-vendor-derived-features(a real figure: oneds-areegexport’s raw 8–12 Hz power beside its vendor quality column);pf-dropped-samplespromoted to Level 7.common.DATASETSgainsds-areegfrom the directory so the figure writers can cite it. All three lessons shipstatus: draft; every keyed number is cited to its notebook cell.check-contentlearns the objective verb “open” — and, once--strict-draftswas run over the finished track, “combine”, “assemble”, “structure” and “package”; with those the full published gate passes over all twelve Phase 5 drafts with 0 errors. - Phase F, finished: L7.13–L7.16 and the path, as drafts. L7.13 The feedback signal with
nb-7-13-feedback(three derivations of band power per block and what each adds to the budget; smoothing quantified as measured latency by the loopback probe, 616 ms against 510 exact; the baseline from calibration and what an adaptive threshold does to a learning claim; the channels of a montage combined with the combination stated;w-latency-budgetfeedbackmode embedded). L7.14 A protocol that can fail withnb-7-14-protocol(the naive trend reproducesnb-7-3’s 8 of 12 through the library to 10⁻¹⁶; the four sham modes; the valid sign-flip test and its power table — and the yoked minutes do rise over a minute, so the claim is the contrast, not the null; the sealed token;crednf_report). L7.15 A first BCI on four channels withnb-7-15-bci(the chance band held to Level 6’s helper; eyes closed against eyes open on the occipitotemporal replica with a time split, median 0.79, pooled 0.76 on 144, the leaky shuffled split 0.96 beside it; the P300 at 16/8/4 channels on one dry-headset subject, 0.944/0.940/0.846 AUC; SSVEP by CCA on the planted flicker with the alpha caveat measured; a blink switch labelled EOG;BCILoopblock by block). L7.16 Build the application withnb-7-16-application(the two example applications run as programs on the shipped four-channel asset and the synthetic stream; thesession.jsonfields the rubric reads; a pip-project shape with a replay entry point; the probe within one block of the arithmetic — 503.1 against 503.1 ms; the gate over 4 of 4 planted artifact windows; four sham modes sealed and unblinded; CRED-nf five of six with the pre-registration committed and twelve sessions tested; the EO/EC switch on the replica, 44 of 54 pooled over the nine subjects whose decoder was fitted — three never calibrated because the gate held their stream unusable, stated as the gate doing its job; the hardware-run record with every valueTODO(confirm)). The pathpaths/consumer-nf-bci.md: fifteen lessons in the proposal’s order, 1000 minutes, seven skipped prerequisites. Three glossary entries (sham-feedback,pre-registration,chance-band);pf-decoding-leakage,pf-site-device-confound,pf-vendor-derived-featuresandpf-dropped-sampleslink the new lessons. Every page shipsstatus: draft. - Library, for L7.16. The
eo-ecsynthetic scenario (alternating 6-s eyes-closed / eyes-open periods, a cue at each boundary, a planted alpha burst on every closed period — the one two-class state both montage classes can decode);configs/eo-ec-synthetic.yamlandconfigs/alpha-up-oc4-replay.yaml(the alpha loop over the shipped four-channel asset: one asset, two consumers);examples/eo_ec_switch.py(a lamp that closing the eyes turns on) andexamples/blink_switch.py(an EOG switch, labelled as such);tests/test_examples.pyruns the three examples as programs and asserts the rubric’s file-checkable items — the “L7.16 CI job” inside the existinglibraryjob (142 tests collected on a runner, 143 with the hardware-marked one); the hardware-run record template inloop/HARDWARE.md. - Promoted (2026-09-21): the author approved the Phase 5 drafts. L7.10–L7.16,
path-consumer-nf-bci, the three new pitfalls and theds-cognitive-states-studentsstub page gostatus: published— twelve pages, after--strict-draftshad applied the full published gate to them with 0 errors. TheTODO(confirm)markers in the key comments stay, under the author’s 2026-09-19 ruling that disclosed gaps ship; the notebooks keep their “draft — for expert review” header line as every other notebook does. eegloopis public: MIT, and a standalone repository (2026-09-21). Spec §13 item 4 answered — the package is MIT (loop/LICENSE, copyright the author;pyprojectpoints at the file) — and it is published at neurokinetikz/eegloop as a one-waygit subtreemirror ofloop/: the monorepo stays the source of truth and.github/workflows/sync-eegloop.ymlpushes the split on every change toloop/(it skips itself until the deploy-key secret exists). So that a clone is a working package,loop/assets/now mirrors the five shipped files the replay protocols and the latency test read —alpha-ec,oc4-ecandtraces.json— byte for byte from the site’s copies, with their ODC-By attribution restated inassets/README.md;tests/test_assets_mirror.pyholds the two copies equal whenever the site is beside the package. The README’s quick start runs from the package root and names the monorepo’s prefix once. Verified by cloning the public repository into an empty directory: 143 tests (7 skipping, the ones that cross-check against the course’s notebook helpers), the four-channel replay protocol running at its stated 610 ms budget.- After the author’s approval: the Phase 5 gap audit and its fixes (2026-09-21). Four auditors read the
proposal, the CONTRACTS addendum and the spec against the repository and reported 78 candidate gaps; a
fresh reader tried to refute each — 60 confirmed (50 actionable, 10 the author’s), 18 refuted
(
site/notes/integration-phase5.md). The actionable ones are closed in five commits: content and notes (the path’s skipped prerequisites; a mains line, not a hole, on the vendor-features figure; links, pointers and key comments; the lab pages; the stub page’s verified fields); the library (the budget’sdecisionsection,with_probe,KeyboardMarkers, the driver’s marker row, the README’s protocol schema, nine tests including measured reward and decision latencies, serial-number checks in both renderers); the figures (a railed channel; the real replayed-sessions panel; the manifest re-registered); thefeedbackmode’s filter-Hilbert derivation (the spec’s “envelope stage via the existinghilbert.ts”, held to the library’s reference to 2e-5 µV); the notebooks (helpers_l7.pyappended withimport_eegloop, the replica andds-areegloaders; the own-recording pass in all seven; all re-executed with every keyed number unchanged); the three other Zenodo records read further and entered as directory-only stubs; the spec’s §8 row, §9.2 (34), §10.4 and §14 brought up to what shipped; track noteslibrary.md,widget-latency.md§8 andintegration-phase5.md. data-p5-licences: the Zenodo record read from the record. Zenodo 20089290 entersdata/directory.yamlasds-cognitive-states-students(an id from the record’s title, per the proposal) with its licence verified in three places —cc-by-4.0in the record metadata, the legalcode link on the landing page, and nothing inside the archive (59 CSVs, no LICENSE or README) — so it derivesallowed, class A; the draft dataset page is generated for it alone and the registry entry stays the author’s (§10.1 rule 3). Two findings the record does not state: the timestamps are written to the millisecond, so the rate must be counted (256.02 Hz over one file’s span; 3,885 intervals read as gaps that are not), and the data dictionary describes ametadata_subjects.csvthe archive does not contain. Whether the app’s notch was on isTODO(confirm). One 3.9-MB file was read and deleted; the three other Zenodo records the proposal listed (22093536, 8429740, 10371068) were read at the metadata level — all threecc-by-4.0, open — and stay out of the directory until the author picks one.site/notes/data-p5-licences.md.- Phase E: the headset source.
BrainFlowSource(board_key)— the driver behind the sameSourceinterface as a replayed file,StreamInfobuilt from the driver’s board descriptor at runtime with any disagreement against the board table recorded, blocks split at every loss the package counter shows (modulus inferred at the first wrap; the increment histogram kept for the report), timestamps rebased to the session.BOARDSis the one table that names a device (muse-2,muse-s,muse-s-athena,brainbit; the deprecated*_BLEDids refused by name);loop/HARDWARE.mdholds the per-device facts with verified dates and the list of what a report must still settle. Pairing details reach the driver from the environment only, so no protocol, log, sidecar or report can carry one.eegloop check— the acceptance report on any source: rate measured against rate claimed, drops, timestamp structure (the packet-burst signature of arrival-time stamping), per-channel DC, spread, flatness, the mains line at 50 and 60 Hz, the bandwidth edge (an on-device low-pass shows as a cliff), gate-label prevalence; verdicts infirst_look_checks’ names;eegloop devices. Tested on a fake board with the driver’s interface — a planted five-packet loss, a wrapping counter, packet-identical stamps — and on the synthetic scenarios;pytest -m hardwareruns the one test that needs a headset, only withEEGLOOP_HARDWARE=<key>. The LSL source waits on its binding decision and says so. - One disagreement found and recorded, not reconciled. The repository has three things called
a “pop”:
detectors.py’s sustained step,helpers.detect_artifacts’s sample-to-sample jump, andeegpipe.synthetic’s 20-ms transient. The first test of the gate against the synthetic stream failed on exactly that: the generator planted the third, the gate looked for the first. The gate now fires on either of the first two and the generator plants what the gate’s criterion means;loop/README.mdsays so.
Changed
- The gate’s verdict: suspect is fed back, unusable is closed. The first whole-session run
froze every block: the un-notched synthetic stream shows a mains line,
line-noisemarked every channel suspect, and the gate counted only good channels toward its minimum. A visible mains line is the normal state of a recording and the band-pass removes it, so suspect channels now count as usable and the block is fed back carrying the label (gate_stateis insignal.npz); only an unusable channel, or too few usable ones, closes the gate. - A pop claim needs a neighbour. On a one-channel stream the “that its neighbours do not share”
half of both pop criteria was vacuously true, and the shipped eyes-closed trace — 280-µV alpha
waves at 160 Hz, clearing the 100-µV jump threshold on their own — drew six pop closures. A pop is
a local event; with no other channel its locality is untestable, so the gate makes no pop claim and
describe()says so, as it already did for blinks without a frontal channel. - The inverted sham inverts about the calibration baseline, the centre that exists when the
value is shown;
helpers_l7.sham_feedbackinverts about the whole-session mean, which needs the future. Recorded infeedback/sham.py, not reconciled; the notebook that compares them prints both.
Fixed
eegloop.session.Recorderwrote a block-interleaved file. Each block’s channels × samples chunk was appended in turn, which no reader of the §4.5 layout (all of channel 0, then channel 1, …) understands; the Phase C round-trip test compared the file with itself and passed.nb-7-11’s record-then-replay comparison found it (a 389 µV maximum difference). The recorder now buffers the blocks and writes the file channel-major atclose()(about 15 MB an hour for four channels at 256 Hz, stated in its docstring), and the test compares the read-back samples with the source’s.eegloop check’s rate row read a known loss as a slow clock. The rate measured from the timestamps now counts the samples a detected gap removed as elapsed samples, so the drops row reports the loss and the rate row reports the clock: on the syntheticgapsscenario it reads the planted 200 ppm of drift (0.02 %) instead of 0.23 %.
Known gaps
- The library’s synthetic and replay paths are complete through Phase E; the headset path is built
and tested against a fake board, and every per-device fact
HARDWARE.mdmarks TODO(confirm) waits on aneegloop checkreport from the author’s own headsets. Emotiv and Neurosity routes wait on spec §13 item 6; LSL on its binding. The content and notebook tracks (L7.10–L7.16 and the path) are written and executed, allstatus: draftfor the author’s review;site/notes/content-L7c.mdandnotebooks-L7c.mdlist what each notebook found that the proposal had guessed differently. The four Zenodo records are verified class A on their records’ statements (site/notes/data-p5-licences.md; one archive unopened, one unread beyond its readme) but nothing derives from any of them until the author adds a registry entry; no script exists that could. Motor imagery is not available on either consumer montage the course names (no C3/C4); the imagery protocol exists to show the loop’s shape on a planted answer, and says so in its own header. - The
lslextra is undeclared until the binding is chosen at a named release (mne-lslpulls MNE;pylslneeds liblsl).
[Unreleased] — All 161 pages published (2026-09-19)
The author reviewed every page and promoted the lot. status: review no longer appears anywhere in
the content; 161 pages are published and the status badge is gone from the site.
Changed
- TODO(confirm) no longer blocks publication, by the author’s ruling. §5.3 made a marker a
publication blocker, which assumed the only way to avoid shipping an unverified claim is to
withhold the page carrying it — the wrong trade when the page is otherwise reviewed, since it
hides a whole lesson to avoid admitting a footnote. Two neighbouring rules were the same shape (an
exercise with no answer key, a notebook a page names before it exists) and now share one
disclosed()policy incheck-content. What unites them is that the page already tells the reader: the marker is literal in the prose, the exercise says “No answer key yet” and declines to grade, and the notebook card carries a “notebook not yet indexed” badge with its buttons disabled. They remain reported as warnings.--strict-todorestores the original gate. - A checker bug, found by promoting. The rule meant to keep a published lesson’s notebook
runnable read the lesson’s
datasets:list — what the lesson discusses — rather than what the notebook downloads. It fired on L5.4, L5.5 and L5.6 for namingds-fsaverage, which they name precisely because its licence blocks it, while their notebooks downloadds-lemonor nothing. It would equally have missed a notebook fetching a closed dataset its lesson never listed. It now readsnotebooks/index.json. /start/and/about/were out of date and are corrected./start/still told readers that only three lessons existed and the rest were hidden stubs./about/still called the site name, domain and repository undecided.
Added (analytics)
- Plausible analytics, at the author’s request, in the
<head>of every page. It is the site’s only third-party request — no cookies, no cross-site identifier, nothing to consent to./about/’s privacy section names it rather than claiming the site talks to nobody, and says that a content blocker stops it with no loss of function. Note that this makes “no analytics”, stated in the Phase 0 decisions inREADME.md, historical rather than current.
Added
TodoNote. Publishing removed the badge that used to explain the markers, which would have leftTODO(confirm)sitting in prose marked finished with nothing saying what it meant. Each page now counts its own markers and says. On lessons, capstones, labs, pitfalls and paths — 103 pages; dataset pages already had their own note.
Fixed
- The
pipelinesCI job, which had never passed. 17 failures and 52 errors all reduced to one undeclared package:pipelines/pyproject.tomlnever listed scikit-learn, and MNE implementsmethod='fastica'through it. It passed locally throughout, because this machine has scikit-learn installed for the notebooks — which is how a missing declaration hides, being present for an unrelated reason everywhere except the one environment that installs only what is declared.
Known gaps
- A second cache that invents faults. After 161 content files changed at once, the build reported
Duplicate id "…" foundfor collections containing no duplicate; clearing.astroproduced a clean build from identical sources. That is the second cache here to do this (the first wasnode_modules/.vite, twice).npm run dev:cleannow clears both andbuild:cleanjoins it. Reproduce against a clean build before believing a strange symptom. - The two item banks are still
algorithmic. The page review does not cover them: 67 drill items and 189 scroller annotations remain unreviewed, andscripts/apply-label-review.pycan never writeexpertwithout a verdict.
[Unreleased] — Deployed to eeg.neurokinetikz.com (2026-09-19)
§13 items 1 and 3 are answered. The site is live at https://eeg.neurokinetikz.com/, published from this
repository by .github/workflows/deploy.yml on every push to main.
Added
- Deployment.
deploy.ymlstopped being a placeholder: it renders the notebooks, builds, runs Pagefind, asserts every notebook fragment exists, and publishes to GitHub Pages. HTTPS is enforced. - A sitemap and
robots.txt. Neither could exist whilesitewas a placeholder, because a sitemap needs an absolute origin to write into<loc>. 233 URLs. It lists what the build emits, which includes the 161 pages still atstatus: review— they are reachable, so they are listed. That is a different question from the feed’s, which carries published items only; the sitemap answers “what is reachable” and the feed answers “what is finished”.
Changed
- A custom domain serves at its own root, so there is no
basepath. This is the decision with the longest reach in the repository: 466 internal links are root-absolute, and they are correct only because the site is served at/. Publishing at a bare…github.io/eeg/URL instead would require abaseand a rewrite of every one of them. A base-path implementation was written and then reverted when the domain was chosen. - The domain is configured in the repository’s Pages settings, not by
site/public/CNAME.actions/deploy-pagesdoes not read a CNAME file — a fact worth recording because the file’s presence suggests otherwise. It is kept so the setting survives redeploys. - Commit authorship rewritten to GitHub’s
users.noreplyalias, which GitHub’s email-privacy setting requires (it rejects the push otherwise, GH007).refs/original/is retained locally as a backup.
Known gaps
- “Open in Colab” stays hidden. The repository is private and the published site is public, which GitHub Pro
permits, but Colab cannot read a private repository.
REPO_IS_PUBLICinsite/src/lib/site/config.tsis the single switch that turns the buttons on for all 59 notebook cards if the repository is ever made public.
[Unreleased] — Phase 4, Level 7 and polish (2026-09-18)
Built by eight tracks in two waves. This completes §12: every phase of the build plan is done.
Added
- Lessons all eight Level 7 electives and C7, the final capstone. Every level of the curriculum now has a body: 56 lessons, 8 capstones, 167 checkable exercises.
- Widgets
w-latency-budgetand thesleepmode ofw-raw-scroller— 26 widgets, the complete §8 catalog. The latency widget decomposes a real-time budget into filter group delay, buffer and processing rather than printing a total, and makes the zero-phase point concrete: asking for zero phase in a live loop costs a look-ahead of N−1 samples, and run per block it returns a negative delay, an output ahead of its input. - Notebooks 7 more, 59 in all, each executed with its outputs stored.
- Site a
/citepage assembling what the catalog already records; verified “In other tools” sidebars for every level; and the first accessibility audit, run against the built output in both themes.
Changed
- Two dataset licences verified from primary sources, and a third found wrong in the catalog.
ds-sleep-edfqualifies (ODC-By 1.0, derivative databases expressly covered).ds-bci-iv-2adoes not: it is CC BY-ND, so its lesson may download, compute and publish benchmark tables but may ship nothing derived from the signal — the community summary of “open with attribution” is wrong on the decisive point. Andds-mpengwas recorded under its descriptor paper’s licence rather than the data’s: the paper is CC BY, the data are CC BY-NC, downstream of consent given for non-commercial research only. Nothing had ever derived from it. The registry fix is §10.11 item 0. derive_snippetsrefuses no-derivatives licences explicitly. It returnednoforCC-BY-ND-4.0only because that spelling is absent from the permissive list — the right answer for the wrong reason, and correcting an apparent typo would have opened it silently.- “Expert” meant two different things. A sleep hypnogram scored by the recording’s own technologist is genuinely expert, but §4.5’s promotion rule — an annotated view leaves
draftwhen every item isexpert— means the author reviewed it. A third party’s scoring would have satisfied a gate that exists for the author’s judgement. Anexpertlabel must now carryreviewed_atorsource. - Accessibility. Nine classes of failure fixed, the largest being 1,868 scrollable regions unreachable by keyboard. That remedy had to be remedied: the first version used a landmark role, so a notebook page acquired dozens of identically-named landmarks and a previously-silent rule began failing. Caught by re-measuring after the change. Two rounds of target-size failures, the second only visible once the first was fixed.
- Exercise states read as what they are. An unfilled exercise advertised “Accepted within ±0”, which it could not honour since it declines to grade until its notebook runs. Three states now: a tolerance, an exact answer required, or no key yet.
- The two group-contrast capstones contradicted each other on subset size, thirty per group against ten to twenty. Both now use the tighter figure and both name the ambiguity: §11’s number is written for a single-cohort capstone and the binding constraint is the ten-minute runtime.
Known gaps
- Author review of every draft, label and answer key; all 161 content pages remain
status: review, and the two Phase 0 item banks (67 drill items, 195 scroller annotations) are still unreviewed. The review tool is built:cd site && REVIEW_TOOL=1 npm run dev. - §13 items 1 and 3 (site name and domain; repository name) still block deploy, canonical URLs and the Colab buttons — the only disabled control left on 59 notebook cards.
ds-mne-sample’s licence is a third open question; answering it unblocks a real head model, L5.4’s original exercise, L5.5, L5.6 and part of C5. ds-srm’s EDF headers declare no unit, so every amplitude reads 10⁶ too large, and the dataset is self-consistent about it.mne-bids-pipelineruns on it, succeeds, and writes a report in which every microvolt is wrong. Recorded as a caveat; only one notebook loads it and no asset derives from it.- moabb’s default download channel for
ds-bci-iv-2ais not the one whose licence was verified. Both notebooks pin the verified provider; whether the default republishes under the same terms isTODO(confirm). - Two figures skipped deliberately — no licence-clear dataset holds a marked epileptiform discharge or a scanner artifact, and simulating either would fabricate what those lessons teach people to recognise. L7.7 ships with no widget, no notebook and no figure.
- No compact CNN in L7.1 (
braindecode/torchdeliberately absent); a filter-bank CSP stands in and says what it does not answer. - TFCE ships in neither cluster widget.
[Unreleased] — Phase 3, Levels 4–6 complete (2026-09-18)
Built by sixteen tracks in two waves against the Phase 3 addendum of site/CONTRACTS.md.
Added
- Lessons all seven Level 4 (time-frequency and oscillations), all seven Level 5 (connectivity and spatial analysis) and all six Level 6 (inference and rigor) as full drafts, with C4, C5 and C6. Checkable exercises rise from 65 to 136; every one in Levels 0–6 has a filled key whose comment states the subject, the parameters, the tolerance and the reason the tolerance is what it is.
- Widgets
w-evoked-vs-induced,w-phase-clock,w-wavelet-explorer,w-tf-baseline-explorer,w-burst-detector,w-volume-conduction-sim,w-csp-explorer,w-garden-of-forking-paths, plus theforwardmode onw-dipole-to-scalpand thetfmode onw-cluster-permutation-viz— 25 widgets in all.registry.tsis now generated rather than transcribed. - Notebooks 22 more (
nb-4-1…nb-6-5and four capstones), 52 in total, each executed with its outputs stored, plushelpers_l4/l5/l6.py.statsmodels,scikit-learnandmne-connectivitypinned;bycycleoptional with a documented fallback. - Site progress export and import (plan-then-apply, seven typed refusal codes, a refusal leaves storage byte-identical); “In other tools” sidebars for Levels 0–3 with every claim verified against EEGLAB 2026.0.0 and FieldTrip 20251218; the statistics thread wired across nine lessons; a dev-only review surface for the two Phase 0 item banks with an applier that can never mark an item expert without a verdict.
- Tooling
scripts/merge-manifest.py(parallel data tracks write manifest parts),scripts/gen-widget-registry.py,scripts/apply-label-review.py.
Changed
- Two dataset licences failed the §10.7 gate and no boundary-element head model ships.
ds-fsaverageis settled and does not qualify: its licence covers data as well as software and permits derivatives only by propagating the whole agreement onto every copy. Every convenient source is silent — the copy MNE ships contains no licence file, the hosting node returns no record, and MNE’s dataset documentation names none — so a check of those three would have concluded there was nothing to worry about.ds-mne-sampleis genuinely contested and is a new §13 decision: its own documentation restricts use to familiarisation, its download channel carries nothing, a public mirror declares CC0 while dropping the restriction sentence, and the archive bundlesfsaverage. Unlike ERP CORE there is no strictest-reading compromise, because “familiarisation only” cannot be complied with by being stricter. Consequently §8’s “precomputed BEM maps” and §6 L5.4’s “sphere vs BEM” exercise are not possible. What ships is two concentric sphere models, one shell against four, flaggedis_bem: falsewith a disclosure the widget prints verbatim, and L5.4 now asks “one shell versus four — what does the skull do?”. Recorded as a deviation from the spec. - §6’s phase-locking positive control does not work, and the lesson said a failing pipeline is broken. Over 30 recordings the paired test — stimulus against silence within each recording, each normalised by its own neighbourhood — gives +0.259 dB, t(29) = 0.33, p = .745; power at the nominal frequency is 0.586× its own neighbourhood and none of the 30 reaches 2×. The archive names the phase “Fixed Auditory Stimulus” and states no rate; the rate was this site’s inference. L4.5 now reports the measurement as its lesson and uses two controls that do work.
data/directory.yamlcarries the finding and a question for the author. - Share-alike now reaches the reader. Seventeen ERP CORE sidecars named the licence without marking themselves share-alike and three carried no attribution; two different attribution strings were in use. Every asset now carries the complete one, sixteen pages render the obligation and the credit, and
check-contentrejects a sidecar that names a share-alike licence without both. - An unfilled exercise was grading answers. A null key coerced to zero against a default tolerance of zero, so a learner typing
0was told they were correct. All four checkable types now decline to grade and say why; the rule lives in a tested module. - The content checker gained three rules: every array whose entries claim a
label_sourceis validated (a sidecar was shipping a value the spec does not allow), share-alike assets must carry their attribution, andscripts/scrub-notebooks.py --checkis a CI step alongside a new job that runs thepipelinestests.
Known gaps
- Author review of every Phase 3 draft, label and answer key; all 161 content pages remain
status: draft. ds-mne-sample’s licence is a new §13 question. Answering it unblocks a real boundary-element model, §6’s original L5.4 exercise, L5.5’s inverse comparison, L5.6’s connectome and a quarter of C5.nb-5-7takes 19 minutes and breaks the §11 ten-minute budget; 9 seconds of that is compute and the rest is one host serving at a twentieth of the speed of the other two. Shrinking its subject survey would delete the selection-effect disclosure L5.7 turns on. The author decides which to keep.- §6 words L4.4’s exercise as a peak where the shipped key is a window mean; the prompt is unambiguous as written but the intent is the author’s to confirm.
- TFCE ships in neither cluster widget: it needs its own null distribution and did not fit the budget. Both say so rather than relabelling what they do have.
ex-6-2as §6 words it has no separable answer; it should ask for standard errors.- The Level 4 and 5 answer keys disagree with their notebooks in three places, each with the cause found and both numbers printed: two skull-effect figures differ because the widget evaluates at its nearest stored grid point and the notebook at the exact position, and one coherence noise estimate differs by a single draw.
[Unreleased] — Phase 2, Levels 2–3 complete (2026-09-18)
Built by twelve parallel tracks against the Phase 2 addendum of site/CONTRACTS.md. The tracks were
interrupted twice by a session limit and finished from the state on disk rather than restarted, so the
repository history for this phase is five commits rather than one.
Added
- Lessons all eight Level 2 lessons (L2.1 loading and BIDS, L2.2 bad channels, L2.3 re-referencing, L2.4 filter choices, L2.5 artifact rejection, L2.6 ICA, L2.7 ASR/SSP and alternatives, L2.8 the pipeline) and all seven Level 3 lessons (L3.1 epoching and baseline, L3.2 the ERP and its components, L3.3 measuring ERPs, L3.4 topographies, L3.5 SNR and trial counts, L3.6 single-trial approaches, L3.7 statistics for ERPs) as full drafts; every checkable exercise in Levels 0–3 now has an answer key with its subject, channel, window and tolerance recorded beside it.
- Widgets
w-bad-channel-detective,w-threshold-tuner,w-ica-component-gallery(a seeded 20-component drill with a confusion table),w-reference-explorer(waveform and topography modes),w-epoch-builder,w-erp-averager,w-measurement-explorer,w-cluster-permutation-viz— 17 widgets in total, each with folder tests and a lab page;registry.tsregenerated. pipelines/theeegpipepackage: the canonical step order as code (load → montage → bad channels → filter → interpolate → re-reference → ICA → epoch → reject),PipelineConfigfrom YAML, a run log that records a failure as a row rather than raising, HTML QC reports, version pinning and seeding, a CLI, three configs (erpcore-p3,eegbci,synthetic) and 123 tests. A subject that fails does not stop the cohort.- Notebooks
nb-2-1…nb-2-8,nb-3-1…nb-3-7, and the capstonesnb-c2-clean-pipelineandnb-c3-replicate-erp-core— 17 more, 30 in total, all executed with outputs stored;_shared/helpers_l2.pyand_shared/helpers_l3.py;pyprep,mne-bids,autorejectandpandaspinned, withmne-icalabel(plusonnxruntime) andasrpyas optional packages that each degrade to a documented fallback. - Data
extract_p2_widgets.py,make_ica_gallery.py,make_topomap_matrices.py,make_cluster_fixtures.py,make_figures_p2.py,fetch_erpcore.py; the manifest is now 157 records and 43.4 MB, with an assetkindtaxonomy (timeseries,matrix,activation,spectrum,index,figure,json) so a topography matrix is no longer validated as if it were a µV time series. - Pitfalls 31 with full bodies, up from 15.
- Paths
/paths/erp,/paths/oscillations,/paths/bci,/paths/realtime. - Tooling
scripts/scrub-notebooks.py(rewrites machine-specific absolute paths out of executed notebooks, in outputs as well as source;--checkfor CI) andscripts/merge-notebook-index.py.
Changed
- ERP CORE’s licence is recorded as CC BY-SA 4.0 (spec §13 item 15, answered 2026-09-18). The licence is contested at source and three real statements disagree: the
LICENSEfile shipped with the data says CC BY-SA 4.0,dataset_description.jsonsays CC0, and the OSF nodethsqgrecord says CC BY 4.0. Spec §10.7 makes the most restrictive reading govern. Derived assets ship, each carrying CC BY-SA 4.0 and the attribution theLICENSEfile asks for; share-alike binds anything derived from these data.data/directory.yamlgainedlicense_statusandlicense_decision, and bothbuild_dataset_pages.pyandcheck-content.tsnow gate share-alike and contested licences on an explicit decision, so the ruling opened this dataset alone and leftds-hbnatsnippets: no. eegpipe.run.scrub_pathsrewrites absolute paths out of a stored traceback, so a run log and the QC report built from it can be handed to someone else.w-cluster-permutation-vizshipschannel_adjacency, the 78-edge Delaunay neighbour list from the montage, so the browser re-clusters over the same neighbourhood the shipped null distribution was built on instead of falling back to MNE’s array lattice.w-ica-component-gallerynames, in the end-of-session summary only, the classes its drill offers that the loaded decomposition contains no example of. ICLabel found no cardiac and no single-electrode component in these three subjects, so two of the seven buttons were never correct and nothing said so.- Wall-clock test budgets are a regression guard, not a benchmark:
bestOf(n, …)againstregressionCeiling(expectedMs)with 8× headroom (EEG_PERF_FACTORto override), after four timing assertions failed under a load average of about 50. data/scripts/common.pyreads the ERP CORE facts fromdata/directory.yamlat run time instead of holding a copy, which is what let two tracks write two different licences.
Known gaps
- Author review of every Phase 2 draft, label and answer key;
label_sourceisalgorithmicthroughout and all 161 content pages remainstatus: draft. ex-2-7-snr-asr: asrpy 0.0.8 and the documented NumPy method disagree about what a cutoff of 20 SD means — 79 % of the signal RMS replaced against 17 % — and a reviewer must settle which behaviour the published key quotes.ex-3-5-minimum-trialsrests on an SME ≤ 1 µV threshold that is a course decision, not a literature value.- ICA does not converge for 9 of 10 subjects at
max_iter: 500; the run log records the flag rather than failing, which is correct, but a cohort that flags nine in ten deserves an author’s eye. steps.filter.ica_copybuilds its ICA copy at 1–30 Hz whilenb-2-6-icaandw-ica-component-galleryfit at 1–100 Hz. The difference is deliberate and each says so, but a component index is comparable within a source, not across.FULL_COHORT = Truein the capstones has not been executed (a further ~1.2 GB of download).- The
data/downloads/erpcorecache was deleted after the tracks released it;data/scripts/fetch_erpcore.pyrepopulates it.
[Unreleased] — Phase 1, Levels 0–1 complete (2026-09-17)
Built by nine parallel tracks against the Phase 1 addendum of site/CONTRACTS.md and integrated the same day.
Added
- Lessons L0.1, L0.2, L0.3, L0.6, L1.1, L1.2, L1.3, L1.4, L1.6, L1.7 as full drafts (every §4.1 section; answer keys computed or derived from the notebooks,
TODO(confirm)where the author must confirm); Level 0/1 index bodies trimmed to prose. - Widgets
w-sampling-explorer(hardware/math),w-montage-explorer,w-dipole-to-scalp(intro; analytic homogeneous-sphere potentials validated against MNE to < 1 %),w-build-a-signal,w-welch-explorer(welch/window),w-aperiodic-explorer(fit/compare), with folder tests and lab pages;registry.tslists all nine. - Data
data/scripts/extract_p1_widgets.py,make_montage_positions.py,make_dipole_fixtures.py,make_figures.py; assets for the six widgets (EEGMMIDB, Iowa PD; specparam fits for 12 subjects; 339-electrode positions from MNE’s standard_1005; dipole fixtures from MNE’s sphere model) and 13 figures undersite/public/figures/; manifest now 109 records including JSON and figure kinds. - Pitfalls full bodies for
pf-trigger-offsets,pf-dropped-samples,pf-bridged-electrodes,pf-site-device-confound,pf-group-demographic-confound,pf-aliasing-on-downsample,pf-zero-padding-resolution; Phase 0 pitfalls wired to real Example figures. - Notebooks
nb-0-2-montages,nb-0-3-first-load,nb-0-6-first-look-report,nb-1-1-resampling,nb-1-2-fft,nb-1-3-psd,nb-1-6-line-noise,nb-1-7-specparam, capstone scaffoldsnb-c0-recording-report,nb-c1-spectral-fingerprint;_shared/helpers_l1.py;index.jsonmerged fromindex-parts/(13 notebooks);specparam==2.0.0rc4andedfiopinned. - Site Pagefind search (⌘K modal,
/search, drafts excluded from the index unlessSHOW_DRAFTS=1),/feed.xml(published entries only), resilientFigurewith sidecar provenance, capstone-aware/notebooks, “used on this site” filter on/datasets; lab sidebars no longer duplicate body sections. - Validation
check-content.ts: manifestpath_roots, purely synthetic JSON/figure products, draft gate for notebook references, wiki-link grep limited to prose (not.pyor notebook code cells).
Known gaps
- Author review of all Phase 1 drafts, labels and answer keys; dataset pages are not promoted.
w-montage-explorer,w-dipole-to-scalp,w-welch-explorer,w-aperiodic-explorership generated placeholder screenshots until replaced by browser captures.- L0.1’s three-panel resolution-ladder figure (scalp vs intracranial vs rodent) is not generated: the intracranial and rodent sources were not downloaded in this phase.
- Two
psds.jsonfits (S004, S009 eyes-closed) re-evaluate below their stated R² (double-alpha decompositions); the aperiodic widget readspeak_paramsas summed heights.
[Unreleased] — Phase 0, vertical slice (2026-09-17)
Built in parallel by ten agents against site/CONTRACTS.md and integrated the same day (build, unit tests,
content validation, headless-browser smoke test and Lighthouse all pass; see README.md). The author’s review is
pending. Every lesson, lab and dataset page ships status: draft.
Added
- Site scaffold — Astro 5 with content collections and MDX, Svelte 5 islands, uPlot; design tokens and
global styles; layouts and routes for
/,/start,/curriculum/…,/labs/…,/pitfalls/…,/datasets/…,/notebooks,/paths/…,/glossary,/about,/changelog,/404. - Content model — schemas for lessons, levels, capstones, labs, pitfalls, datasets, paths, glossary,
reading and pages (
site/src/content.config.ts, spec §5.2). - UI components —
WidgetFrame,ExerciseBox,PitfallBox,NotebookCard,Callout,Figure,Cite,LessonNav,OtherTools,LevelProgress,LadderGraphic,ProgressTracker; localStorage progress store. - DSP library —
site/src/lib/dsp/(FFT, windowed-sinc FIR, Butterworth IIR / SOS, filtfilt, Welch) tested against SciPy fixtures generated bydata/scripts/make_dsp_fixtures.py. - P0 widgets —
w-raw-scroller,w-spot-the-artifact,w-filter-sandboxwith READMEs and lab pages. - Data pipeline —
data/scripts/extraction scripts for the three widgets,data/manifest.jsonwith provenance and checksums, scrubbed catalog snapshot (data/catalog/) and generated dataset pages. - Content — draft lessons L0.4, L0.5, L1.5; frontmatter stubs for every other lesson, widget, pitfall,
dataset, path and glossary ID in the spec; reading-list seed (
verified: falsethroughout). - Notebooks —
nb-0-4-browse,nb-0-5-artifact-atlas,nb-1-5-filters, shared helpers, pinned requirements,notebooks/index.json. - Validation —
scripts/check-content.tsimplementing spec §5.3, the §10.7 snippet gate and the §10.10 private-path grep, with--warn-only,--strict-draftsand--verbose. - CI —
.github/workflows/build.yml(build, test, validate, upload dist),notebooks.yml(weekly execution with nbclient, 15-minute limit per notebook),deploy.yml(documented placeholder pending spec §13 items 1 and 3 and the host choice). - Docs — repository
README.md,site/README.md,pipelines/README.md(Phase 2 skeleton), this file.
Known gaps (Phase 0 exit criteria not yet met)
-
Answer keys derived from data, not yet confirmed by the author: L0.4 eyes-closed onset (75 s ± 2 s, from the LEMON segment’s marker; the algorithmic detector says 74 s) and the four L1.5 P3 amplitudes (from
nb-1-5-filtersonds-brain-invaderssubject 1, Pz, 300–500 ms). -
The artifact bank lacks ecg, bridging and drowsiness items (not derivable from the Phase 0 data); 10 of its 67 items are labelled synthetic derivatives (electrode pop, flat channel).
-
Only headless screenshots and SSR/unit tests exercised the widgets; a hands-on browser pass is still due.
-
Labels on every drill item and scroller annotation are
algorithmic; the author’s review toexpertis pending (§4.5). -
TODO(confirm)markers remain in the three P0 lessons and in generated dataset pages where the catalog is silent. -
Colab links and deploy are blocked on spec §13 items 1 and 3.