Make "I want to add an example" a documented path, not a reverse-engineering exercise

[lucapinello]

You asked about a developer who wants to contribute new models, examples, or just use chorus without friction. The model path is now well covered (#201 closed the last gap there). The example path was not covered at all.

Sentence one turned them away

CONTRIBUTING.md opened with "this guide will walk you through the process of implementing a new oracle", and ## Current Priorities listed three kinds of contribution — all of them models. Someone with a variant they care about, who has no intention of porting a neural network, is told immediately that they are in the wrong document. Adding a worked example is the cheapest useful contribution chorus can receive, and nothing invited it.

It was also genuinely undocumented

Four regeneration scripts own different example types, and the matrix mapping example → script → valid --oracle → conda env lived in CLAUDE.md (a file written for Claude sessions), the CHANGELOG, and a May audit report. None of those is where a contributor looks.

That matrix exists because getting it wrong is the most common way a regeneration silently does nothing:

• regenerate_multioracle.py accepts chrombpnet / cherimoya / legnet / alphagenome and pointedly not enformer — whose report comes from regenerate_examples.py
• it also has no --gpu, while the other two do; passing one is an argparse error that scrolls past in a tailed log
• the wrong conda env does not fail fast — a missing oracle package logs Failed to load <track> once per track and carries on, so a run can spend an hour loading nothing

What changed

• Routing table in the first screen — oracle / example / bug-fix-or-doc-fix, each with an honest size estimate, so a reader self-selects instead of bouncing
• New ## Contributing an example or walkthrough — the verified matrix, the real entry shape copied from ENFORMER_EXAMPLES, the strict_ref warning about ref, the four traps, and the six guard tests to expect. The documented pytest command collects 138 tests — verified, unlike the browser recipe that shipped collecting 0
• Priorities broadened — examples, "documentation that was wrong when you read it" (including a repro with no patch), and tests, alongside the three model categories
• examples/walkthroughs/README.md and examples/notebooks/README.md point at the one canonical section rather than restating it

Guard

8 tests in tests/test_contributing_example_path_matches_the_scripts.py pin the table to the scripts' argparse definitions rather than to a proofread:

• every documented --oracle value must be a real choices= entry — negations like no `enformer` are stripped and covered separately
• the no-enformer exception must hold in both directions: if that script ever gains enformer, the test demands the note be removed
• the --gpu asymmetry must stay correctly described
• generate_walkthrough_notebooks.py must stay argument-free (documented as codegen-only)
• every tests/*.py the section names must exist — a documented command that errors is worse than none

Confirmed the choice-guard bites: a fabricated sei in the walkthrough row is flagged, while the legitimate no `enformer` is not.

Verification

• Fast suite 1,993 passed / 30 skipped (up 8)
• test_doc_links_resolve.py 70 passed — the four new in-page anchors and both cross-file links resolve
• The documented guard-test command collects 138 tests
• Matrix re-verified against each script's add_argument calls, not against CLAUDE.md

🤖 Generated with Claude Code