Add opt-in `docs` dev-shell with `d2`

Factor the shared dev-shell toolchain into `basePkgs` + `baseHook`
so extra-tooling shells can extend it, then add a `docs` shell =
base + `pkgs.d2` (the diagram renderer our `.. d2::` sphinx
directive shells out to). Keeps `d2` OUT of the `default` shell so
casual dev envs stay lean.

Enter with `nix develop .#docs`, then build via `uv run --group
docs make -C docs html`.

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

flake.nix

@@ -25,11 +25,11 @@
           cpython = "python313";
           venv_dir = "py313";
           pypkgs = pkgs."${cpython}Packages";
-        in
-        {
-          default = pkgs.mkShell {
 
-            packages = [
+          # shared base toolchain for every dev-shell variant;
+          # extra-tooling shells (eg. `docs`, below) extend it
+          # so heavy/niche deps stay OUT of the `default` shell.
+          basePkgs = [
             # XXX, ensure sh completions activate!
             pkgs.bashInteractive
             pkgs.bash-completion
@@ -42,7 +42,7 @@
             pkgs.${cpython}# ?TODO^ how to set from `cpython` above?
           ];
 
-            shellHook = ''
+          baseHook = ''
             # unmask to debug **this** dev-shell-hook
             # set -e
 
@@ -63,6 +63,26 @@
             # run the `nix develop` cmd with,
             # >> nix develop -c uv run xonsh
           '';
+        in
+        {
+          default = pkgs.mkShell {
+            packages = basePkgs;
+            shellHook = baseHook;
+          };
+
+          # OPT-IN docs shell: `default` + the `d2` diagram
+          # renderer, kept OUT of `default` so casual dev shells
+          # don't pull it in. Enter with,
+          #   >> nix develop .#docs
+          # then build (the `.. d2::` directive auto-detects the
+          # `d2` bin now on PATH; see `docs/_ext/d2diagrams.py`),
+          #   >> uv run --group docs make -C docs html
+          docs = pkgs.mkShell {
+            packages = basePkgs ++ [ pkgs.d2 ];
+            shellHook = baseHook + ''
+              echo "[docs] d2 $(d2 --version) on PATH \
+              — build via: uv run --group docs make -C docs html"
+            '';
           };
         }
       );