Move the reference design notebook into docs/

[hamed]

examples/precision_recall.ipynb → docs/reference-design.ipynb. Pure rename plus the references that named the old path; the notebook's bytes are unchanged (git reports the rename at 100% similarity).

Why

It was never an example. It is the specification the library was ported from — it defines its own inline copies of every function, needs kagglehub and CatBoost to re-execute, and test.yml deliberately excludes it from the notebook job. Next to quickstart.ipynb, which the README tells users to open and run, it read as something to execute.

It now sits beside the docs/reference-design.md that explains which of its odd-looking details are load-bearing and where the library intentionally differs. Same stem, so the pairing is obvious, and docs/ is the read-don't-run path.

The ruff config gets sharper

The per-file ignores for E402, I001, and F811 were keyed on examples/*.ipynb, so quickstart.ipynb inherited all three — but the rationale recorded in pyproject.toml is specific to the reference notebook, and the F811 entry is about its deliberate np/plt re-import in the setup cell.

Measured with those rules re-enabled per notebook:

notebook	E402 / I001 / F811 violations
quickstart.ipynb	0
reference design	8

So the ignores now name the one file that earns them, and quickstart is linted with no exemptions. Both notebooks are still scanned (ruff check --show-files lists both) and both pass.

The formatter still skips both. Reformatting a notebook committed with its outputs is a diff nobody asked for, whichever notebook it is — so the exclude list gained the new path rather than trading one for the other.

Changed references

• pyproject.toml — lint per-file-ignores, formatter exclude
• docs/reference-design.md — self-reference, now "beside this file"
• README.md — the path in the Reference design section
• .github/workflows/test.yml — the comment explaining the CI carve-out, which now also records why it lives under docs/

git diff --exit-code -- examples/ in the notebook job is left as is: it guards the notebook that job actually executes, which is quickstart.

Nothing references the old path any more (grep for precision_recall across md/py/toml/yml is empty), and no test hardcodes either notebook path — test_notebook_golden_values pins values, not files.

Verification

ruff check and ruff format --check clean, 135 tests pass. No source or notebook content changed.

🤖 Generated with Claude Code