Document the docs build/preview flow

Collect the sphinx build + live-preview one-liners (incl. the nix
`.#docs` opt-in shell and the `d2` diagram specifics) so
contributors don't have to reverse-engineer them,

- new `notes_to_self/howtodocs.md` terse cheat-sheet (force-added
  past the `notes_to_self/` ignore, same as `howtorelease.md`),
- a rendered "Building these docs" section in the dev-tips guide
  (`docs/project/dev-tips.rst`),
- a README pointer to the note.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code

docs/README.rst

@@ -110,6 +110,11 @@ Alongside all this we ofc offer "releases" on PyPi::
 Just note that YMMV since the main git branch is often much further
 ahead then any latest release.
 
+Hacking on the docs themselves? The build + live-preview one-liners
+(incl. nix-shell specifics) are collected in `notes_to_self/howtodocs.md
+<https://github.com/goodboy/tractor/blob/main/notes_to_self/howtodocs.md>`_,
+and rendered as the "Building these docs" section of our dev-tips guide.
+
 
 Example codez
 -------------

docs/project/dev-tips.rst

@@ -121,6 +121,62 @@ Every record's header includes the emitting actor and task names,
 so cross-process flows can be stitched back together by eyeball
 (or grep).
 
+Building these docs
+-------------------
+The site you're reading is sphinx_ + the pydata-sphinx-theme_,
+with diagrams authored in d2_ (via our local ``.. d2::``
+directive) and *every* code block ``literalinclude``-d straight
+from ``examples/`` — so what you read is what CI runs, and it
+can't rot.
+
+The one-liner, from any dev shell::
+
+    uv run --group docs make -C docs html
+
+then open ``docs/_build/html/index.html``.
+
+**Nix users**: the d2_ diagram renderer is deliberately kept
+*out* of the default dev-shell so casual envs stay lean; it
+lives in an opt-in ``docs`` shell::
+
+    # enter the docs shell (puts `d2`, `uv` + python on PATH)
+    nix develop .#docs
+
+    # ...then build (diagrams re-render from docs/diagrams/*.d2)
+    uv run --group docs make -C docs html
+
+or as a one-shot without staying in the shell::
+
+    nix develop .#docs -c uv run --group docs make -C docs html
+
+**Live-reload** while editing — rebuild + browser refresh on
+every save::
+
+    nix develop .#docs -c uv run --with sphinx-autobuild \
+        --group docs sphinx-autobuild docs docs/_build/html
+    # then open http://127.0.0.1:8000
+
+How the diagrams resolve,
+
+- ``.d2`` sources live in ``docs/diagrams/``; their rendered
+  SVGs are git-committed under ``docs/_diagrams/`` as a fallback,
+- with a ``d2`` binary on ``PATH`` (the ``docs`` shell, or set
+  ``D2_BIN='nix run nixpkgs#d2 --'``) any stale SVG re-renders at
+  build time,
+- with NO binary the committed SVGs are served as-is, so CI and
+  casual builds need no ``d2`` at all,
+- a ``.d2`` that *fails to compile* is a hard build error under
+  ``sphinx-build -W`` (the last-good committed SVG is left
+  untouched).
+
+The build is currently **warning-free**; keep it that way — the
+``-W`` flag turns any sphinx warning into a hard failure::
+
+    uv run --group docs sphinx-build -b html -W docs docs/_build/html
+
+A terser command cheat-sheet also lives at
+``notes_to_self/howtodocs.md``.
+
 .. seealso::
    - :doc:`/guide/testing` — running the suite, watching trees
      live, examples-as-tests conventions and the zombie-reaper.
@@ -131,3 +187,6 @@ so cross-process flows can be stitched back together by eyeball
 .. _uv: https://docs.astral.sh/uv/
 .. _towncrier: https://towncrier.readthedocs.io/en/stable/
 .. _stackscope: https://github.com/oremanj/stackscope
+.. _sphinx: https://www.sphinx-doc.org/
+.. _pydata-sphinx-theme: https://pydata-sphinx-theme.readthedocs.io/
+.. _d2: https://d2lang.com

notes_to_self/howtodocs.md

@@ -0,0 +1,67 @@
+# How to build + view the docs
+
+The site is `sphinx` + `pydata-sphinx-theme`, with diagrams in
+[`d2`](https://d2lang.com) (our local `.. d2::` directive) and
+*every* code block `literalinclude`-d straight from `examples/`
+(never copy-pasted — what you read is what CI runs).
+
+## TL;DR
+
+```
+uv run --group docs make -C docs html
+firefox docs/_build/html/index.html
+```
+
+## Nix users
+
+`d2` (the diagram renderer) is deliberately kept **out** of the
+default dev-shell so casual envs stay lean; it lives in an opt-in
+`docs` shell:
+
+```
+# enter the docs shell (puts `d2`, `uv` + python on PATH)
+nix develop .#docs
+
+# ...then build (diagrams re-render from docs/diagrams/*.d2)
+uv run --group docs make -C docs html
+```
+
+one-shot, without staying in the shell:
+
+```
+nix develop .#docs -c uv run --group docs make -C docs html
+```
+
+## Live-reload while editing
+
+Rebuilds + refreshes the browser on every save:
+
+```
+nix develop .#docs -c uv run --with sphinx-autobuild \
+    --group docs sphinx-autobuild docs docs/_build/html
+# then open http://127.0.0.1:8000
+```
+
+## Diagrams (`d2`)
+
+- `.d2` sources live in `docs/diagrams/`; their rendered SVGs are
+  git-committed under `docs/_diagrams/` as a fallback.
+- with a `d2` binary on `PATH` (the `.#docs` shell, or set
+  `D2_BIN='nix run nixpkgs#d2 --'`) any stale SVG re-renders at
+  build time.
+- with NO binary, the committed SVGs are served as-is, so CI and
+  casual builds need no `d2` at all.
+- a `.d2` that *fails to compile* is a hard build error under
+  `sphinx-build -W` (the last-good committed SVG is left intact).
+
+## Keep it warning-free
+
+The build is currently 0-warning — keep it that way. `-W` turns
+any sphinx warning into a failure:
+
+```
+uv run --group docs sphinx-build -b html -W docs docs/_build/html
+```
+
+> The rendered version of this note lives in the contributor
+> guide: `docs/project/dev-tips.rst` → "Building these docs".