Declutter the README, and fix six documentation defects

[lucapinello]

Audit of notebooks, examples, documentation and the nulls, plus the README restructure you asked for.
Full report: audits/2026-08-18_post_v075_docs_and_readme_audit.md

The README had grown clutter — and I had added to it

Measured before editing: 24 blockquote asides, 12,229 characters, longest 1,692. Two of the five worst
were ones I wrote earlier the same night, and my version of the aside you quoted had grown a sentence per
release — a pattern that does not converge.

	before	after
aside text	12,229 chars	6,793 (−44%)
longest aside	1,692 chars	704
free-disk bullet	940 chars	~450

Structural, not just shorter:

• One Caveats section holds the four things that can change a number — Enformer cross-process
  variation, the pre-0.7.5 alphagenome_pt splice history, Cherimoya-vs-ChromBPNet magnitude, hg38-only.
  Inline asides became two-line pointers. Caveats are now findable in one place instead of ambushing the
  reader mid-flow.
• Token plumbing moved out of the quick start into the installation section, where you hit it.
• Per-release detail delegated to the CHANGELOG. The README states the rule ("install a tag"); the
  CHANGELOG says which release moved which number. That is what stops this recurring.
• The enformer install itemisation moved from a TLDR parenthetical into the disk-usage section.

Six defects

#	defect	mine?
1	examples/walkthroughs/README.md described Sei by its pre-0.7.4 scope ("40 sequence classes"), in the table the README calls a "full side-by-side comparison" — which also covered 6 of 8 oracles
2	docs/variant_analysis_framework.md still carried the "1–2 % fp32 noise" equivalence claim that 0.7.5 corrected in the README	yes — fixed the README without grepping elsewhere
3	describe_tracks() appears zero times in docs/, including the "Full Python API reference"
4	The null protocol had no record that alphagenome_pt has no null of its own and ranks against alphagenome's — a protocol-level decision, silently violated for 738 tracks. New §8b + the decision-log entry CLAUDE.md required in the same commit as the change	yes
5	examples/notebooks/README.md says each notebook "produces … outputs inline" while 16 code cells across three ship blank
6	The free-disk bullet still said "~13 GiB, not 85" after the total moved to 87	yes

Verified clean

• Nulls — all 9 artefacts: schema_version 4, one build campaign, exact track counts, 10,000-point
  CDFs, and signed flags summing to 24,160, precisely what the protocol claims. The protocol's numbers
  reproduce from the artefacts.
• Notebooks — six library notebooks: no error outputs, no tracebacks, no WARNING lines, all on kernel
  chorus.
• Examples — all six linked walkthroughs ship Markdown + JSON + TSV + HTML with IGV, as claimed.
• README facts — coordinate table (CATCA/ATCA), Cherimoya's 1,149 DNase + 369 ATAC, the 4 K562 ATAC
  experiments, score_ism's 25 bp default, all five sequence lengths, 24 MCP tools, AlphaGenome's 1 bp vs
  128 bp bin split. All exact.

Guards caught three of my own edits

Which is the system working, and one is a lesson about guard design:

• test_no_weights_is_not_sold_as_a_getting_started_option — my compression dropped the "cannot predict"
  phrasing it exists to protect.
• test_live_docs_do_not_claim_a_stale_track_count — my wording "took it from 40 tracks to 21,947" read as
  a current claim of 40 tracks for Sei.
• My own test_the_tldr_install_size_agrees_with_the_disk_table was keyed to the exact sentence "The
  install itself is ~N GiB" and broke the first time that sentence was reworded. Re-anchored on the
  prerequisite bullet — a guard that fails on rewording rather than on drift is noise.

Four false positives are recorded in the report, including my slug function reporting 8 broken anchors
(GitHub emits one hyphen per space, so #cherimoya--catv1 is correct — all 21 resolve) and NPZ provenance
that lives inside build_config rather than under a provenance key.

Gates

Fast 2,146 passed / 34 skipped. Integration 159 passed / 6 skipped / 0 failed. Browser: CI.