Add conservation-score tracks and a unified annotation catalog

[lorenzoruggerii]

GPN-Star, PhyloP 20-way, and PhastCons 7-way become optional IGV tracks on variant reports (analyze_variant_multilayer(..., show_conservation=True)), bulk-downloaded and cached like oracle weights rather than streamed per-region. A new AnnotationStore unifies these with GENCODE GTF annotations and user-added custom entries behind one list/describe/download interface (CLI chorus conservation / chorus annotation, and matching MCP tools), with downloaded bigwigs' declared genome build physically verified against the file's own chromosome-1 length.

[lorenzoruggerii]

Follow-up commit responding to #247's review: 3d0b6b1.

Merged #247 in full first (fast-forward, no changes). This commit then addresses the items it explicitly left open:

Fixed (both were "left for your judgement" in #247, not required fixes):

• resolve_html_path: VariantReport/CausalResult now expose it, and both to_html and the MCP _write_html_report helper call it instead of re-deriving the output path independently — they used to disagree for an output_dir like /data/run.v2, where the dotted .v2 makes Path.suffix non-empty. Regression test included.
• discover_variant no longer renders and writes its HTML report twice. Builds the AnalysisRequest before calling discover_variant_effects (which already accepted one for exactly this) instead of stamping it on after the first write. Regression test included.

Partly closed — the igv.min.js CI-coverage gap:

• Regenerated rs12740374_SORT1_chrombpnet_report.html, one of the two reports CHORUS_BROWSER_SMOKE=1 renders, so it now embeds the new 1.50 MB bundle instead of the old 1.35 MB one.
• Verified with Playwright/Chromium against test_committed_reports_render_in_a_browser.py — not just inferred from size/content: the exact CI smoke subset (11 passed, 1 skipped) and the full 19-report corpus (46 passed) both pass, every canvas paints, no console/page errors.
• Still open: the other smoke report (rs12740374_SORT1_cherimoya_report.html) and 17 more still carry the old bundle. Regenerating cherimoya's needs the chorus-cherimoya env, unavailable in the session that did this work — flagging rather than guessing at a fix.

Shipped — the doc gap:

• single_oracle_quickstart.ipynb gains a Conservation Tracks section (show_conservation=True on the notebook's own GATA1 variant, plus an AnnotationStore.list_annotations() listing), executed end-to-end with real downloaded data rather than left unexecuted. show_conservation, chorus conservation, chorus annotation, and AnnotationStore appeared in no notebook before this.

Left alone, documented rather than patched:

• add_annotation's genome_build check rejects dm6/ce11 even though chorus supports those genomes elsewhere — but the chr1-fingerprint verification scheme it's built on can't apply to them at all (neither has a chromosome named chr1). That's a real design decision about how (or whether) to verify non-mammalian builds, not a whitelist fix.
• _write_html_report's remaining call sites, add_annotation's genome_build table, and the other 17 stale-bundle reports are all still real, just out of scope for this pass.

Full suite: 2182 passed (a pre-existing, unrelated set of ~40 environment-specific failures — stale background/provenance fixtures on this machine — confirmed identical with and without this commit's changes).

[lucapinello]

Could you add a worked example for this before it lands? Right now the feature has no user-facing
entry point: show_conservation, chorus conservation, chorus annotation, AnnotationStore and
the three MCP tools appear in 0 files across README.md, docs/ and examples/, and the PR
touches no notebook or walkthrough. Someone reading the docs cannot discover any of it.

I've opened #247 against this branch with the prose half — a README Conservation tracks section,
the MCP count 24 → 27, and a docs/API_DOCUMENTATION.md entry — plus fixes for nine defects. But the
runnable half is better placed by you, since you know what the tracks are for scientifically.

Either of these would do it; no need for both:

a) A section in an existing notebook — examples/notebooks/single_oracle_quickstart.ipynb already
ends with a coolbox view, so conservation_logo_track() alongside it is a natural few cells. The
catch is the download: ~9.9 GB for entropy, ~45 GB more for the LLR bigwigs the logo needs. A
notebook that can't run without 70 GB is worse than none, so it may need to be phyloP-only (~9.2 GB),
or gated on has_gpn_star_bigwig() with a clear "download this first" cell.

b) A minimal walkthrough — examples/walkthroughs/conservation/<locus>/ following the shape of
the others (prompt at the top, MD + JSON + TSV + HTML). This is probably the better fit: it shows the
feature where it actually pays off — a variant whose conservation context changes the read — and it
sidesteps the notebook download problem because the artefacts are committed.

What would make either genuinely useful rather than a smoke test: a variant where conservation
changes the interpretation. A strong predicted effect at a poorly conserved position, or a weak one
at a highly constrained base. That's the case a reader can't get from the oracle tracks alone, and it
answers "why would I turn this on?" in one figure.

Two things to know if you go the notebook route, both from #247:

• It's hg38-only now — a non-hg38 report raises rather than plotting human scores against other
  coordinates.
• The logo track is p(base) × (2 − H) on a 0–2 bit scale, not clip(1 - entropy, 0, 1). Three
  docstrings (including the blurb rendered into every report) said the latter; Review fixes for the conservation / annotation-store work #247 corrects them, so
  worth not re-copying the old wording.

[lorenzoruggerii]

Hi Luca!

Thank you for pointing this out. I decided to add a minimal walkthrough.

examples/walkthroughs/conservation/SORT1_rs12740374/: scores rs12740374 with ChromBPNet DNase in HepG2 (show_conservation=True) — same variant and effect as the existing variant_analysis/SORT1_chrombpnet walkthrough (+1.376, ≥99th percentile, 1.18× the null max) — and reads phyloP/phastCons/GPN-Star directly at the variant's own base: phyloP −0.046, phastCons 0.001, GPN-Star entropy 0.772/2 bits. So here we have a strong opening effect in a poorly conserved region.

Committed via a new regenerate_examples.py entry (not hand-written) and the codegen'd notebook path, so it's regenerable like every other walkthrough.