Write a docs page

Every hand-authored page in these docs is a MyST notebook — jupytext frontmatter plus a kernelspec — so any of them can run live code-cells with real output and plots. There are two genres, split by reader and by where their cells execute:

• Tutorials (docs/basics/, data-model/, plotting/, fitting/, nifti/, matlab/) demonstrate a task step by step, and are the test suite once they carry a jupytext kernelspec.

• Guides (docs/contribute/) are procedural pages like this one.

The four house-style rules — motivated narrative, one home per concept, every article stands alone, and the MyST palette carries the argument — are the single source of truth in CLAUDE.md § Documentation style.

Working with Claude Code¶

The docs-page skill owns the cell structure, the hidden-assert convention, and the TOC step, and it ships a stdlib-only checker (check_docs.py) that catches what the build stays silent about — a missing target, a dead .ipynb link, a drifted kernel name. Run it on the page you are editing:

uv run python .claude/skills/docs-page/check_docs.py docs/<path>/<page>.md

Its errors are render-breaking. Its warnings deliberately do not gate anything: they are real drift, but too judgment-dependent to block a merge on. The checklist:

- [ ] Genre identified; the matching template and `patterns.md` read
- [ ] Frontmatter exact, `display_name: .venv`
- [ ] `(target)=` + single H1 is the very first content; a target above every header
- [ ] TOC entry in `docs/myst.yml` (unless `testonly_`); no `.ipynb` links
- [ ] `check_docs.py` passes on the page (0 errors)
- [ ] Tutorial only: notebook test run is green
- [ ] Only the `.md` staged — staged, not committed; commit message proposed to the user
- [ ] Remote actions (push, PR, remote branch) confirmed by the user first