diff --git a/docs/PYTHON_CLIENT.md b/docs/PYTHON_CLIENT.md
new file mode 100644
index 000000000..b97843528
--- /dev/null
+++ b/docs/PYTHON_CLIENT.md
@@ -0,0 +1,23 @@
+# OpenAPI Python client
+
+The broker's REST API has a generated Python client, published on PyPI as
+[`jfjoch-client`](https://pypi.org/project/jfjoch-client/) and regenerated from
+`broker/jfjoch_api.yaml` by `update_version.sh` — the YAML is the single source of truth
+(see [OpenAPI](OPENAPI.md)).
+
+- [Client README](python_client/README.md) — installation, quick start, and the index of every
+  endpoint and model.
+- [DefaultApi](python_client/docs/DefaultApi.md) — the full endpoint reference, with a generated
+  example per call.
+
+The per-model pages are generated as well and are linked from the two pages above. They are built
+with the site but kept out of the navigation sidebar on purpose — sixty generated reference pages
+would otherwise be most of it.
+
+```{toctree}
+:hidden:
+:glob:
+
+python_client/README
+python_client/docs/*
+```
diff --git a/docs/conf.py b/docs/conf.py
index 83c96c2db..3a32284ce 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,7 +20,9 @@ extensions = [
 ]
 
 templates_path = ['_templates']
-exclude_patterns = []
+# docs/review/ is gitignored working material (review reports, work plans); Sphinx renders
+# whatever is on disk, so without this a local review file would become a published page.
+exclude_patterns = ['review']
 
 myst_enable_extensions = [
     'linkify',
@@ -66,6 +68,10 @@ html_theme_options = {
     'html_minify': True,
     'css_minify': True,
     'globaltoc_depth': 2,
+    # The generated python-client pages live in a hidden toctree on PYTHON_CLIENT.md: built and
+    # linked, but out of the sidebar - with the default includehidden=True they were 195 of the
+    # sidebar's 256 entries.
+    'globaltoc_includehidden': False,
     # sphinx_material only knows github/gitlab/bitbucket; the repository is Gitea, so 'gitlab' is
     # picked purely for the icon it renders next to repo_url above.
     'repo_type': 'gitlab',
diff --git a/docs/index.rst b/docs/index.rst
index d2f7b2d3a..e557661de 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -61,25 +61,10 @@ Jungfraujoch is distributed under the GPLv3 license.
    CPU_DATA_ANALYSIS
    OPENAPI
    OPENAPI_SPECS
+   PYTHON_CLIENT
    CBOR
    HDF5
    IMAGE_STREAM
    PIXEL_MASK
    WEB_FRONTEND
    TESTS
-
-.. toctree::
-   :maxdepth: 1
-   :caption: OpenAPI Python client
-
-   python_client/README
-   python_client/docs/DefaultApi
-
-.. The remaining python_client/docs/*.md pages are generated per-model reference
-   files linked from the client README/DefaultApi; include them in a hidden glob
-   toctree so they are built without each one warning about being orphaned.
-.. toctree::
-   :hidden:
-   :glob:
-
-   python_client/docs/*