diff --git a/pyproject.toml b/pyproject.toml
index 4106ff04..e8a73c2d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -118,12 +118,19 @@ eventfd = [
 subints = [
   "msgspec>=0.21.0",
 ]
-# TODO, add these with sane versions; were originally in
-# `requirements-docs.txt`..
-# docs = [
-#   "sphinx>="
-#   "sphinx_book_theme>="
-# ]
+# docs generation; build locally via,
+#   uv run --group docs make -C docs html
+# diagrams re-render when a `d2` bin is found, see
+# `docs/_ext/d2diagrams.py` (eg. via `nix run
+# nixpkgs#d2` and the `D2_BIN` env var).
+docs = [
+  "sphinx>=9.1,<10",
+  "pydata-sphinx-theme>=0.18,<0.19",
+  "sphinx-design>=0.7,<0.8",
+  "sphinx-copybutton>=0.5.2,<0.6",
+  "sphinxext-opengraph>=0.13,<0.14",
+  "sphinx-togglebutton>=0.4.5,<0.5",
+]
 # ------ dependency-groups ------
 
 [tool.uv.dependency-groups]