diff --git a/CMakeLists.txt b/CMakeLists.txt
index ccce72fe..30344e54 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -124,6 +124,6 @@ add_subdirectory(xo-imgui)
 # ----------------------------------------------------------------
 # documentation.  must follow add_subdirectory() for satellite projects
 
-xo_umbrella_doxygen_deps(xo_alloc xo_indentlog xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_jit)
+xo_umbrella_doxygen_deps(xo_alloc indentlog xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_jit)
 xo_umbrella_doxygen_config()
 xo_umbrella_sphinx_config(index.rst docs/install.rst docs/glossary.rst)
diff --git a/README.md b/README.md
index 7077d5ec..f2368b11 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,8 @@ Intended for local development work, with source in immediate subdirectories.
 
 ## Getting Started
 
+(Alternatively, see `xo-umbrella2/docs/install.rst` for similar content)
+
 ### Nix shell (reproducible development environment)
 
 If `nix` is available, can get several reproducible build environments.
@@ -37,9 +39,12 @@ including libraries used by running IDE.
 $ emacs
 ```
 
+Can use `nix-shell` to get reproducible environment for cmake build, see `Cmake Build`.
+Alternatively can use full nix build, see `Nix Build`
+
 ### Cmake build
 
-If `nix` is available, you probably prefer the nix build.
+If `nix` is available, you probably prefer the nix build, unless working on XO itself.
 Otherwise continue reading..
 
 The cmake build has two phases, because it needs to bootstrap
@@ -53,7 +58,7 @@ $ cmake -B .build0 -S xo-cmake -DCMAKE_INSTALL_PREFIX=${PREFIX}
 $ cmake --build .build0
 $ cmake --install .build0
 # phase 2
-$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DXO_ENABLE_EXAMPLES=1 -DCMAKE_BUILD_TYPE=debug
+$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DXO_ENABLE_EXAMPLES=1 -DXO_ENABLE_DOCS=1 -DCMAKE_BUILD_TYPE=debug
 $ cmake --build .build --verbose
 $ cmake --install .build
 ```
@@ -64,6 +69,37 @@ or with Vulkan examples
 $ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DXO_ENABLE_EXAMPLES=1 -DXO_ENABLE_VULKAN=1
 ```
 
+### Cmake build documentation
+
+Documentation relies on doxygen, sphinx and breathe.
+```
+# phase 2
+$ cd xo-umbrella2
+$ cmake -B .build -S . -DXO_ENABLE_DOCS=1
+$ cmake --build .build -- docs
+```
+
+Create Html docs in `.build/sphinx/html/index.html`
+
+### Cmake build with coverage
+
+Prepare build
+```
+# phase 2
+$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_BUILD_TYPE=coverage
+```
+
+Run coverage-enabled unit tests
+```
+$ (cd .build && ctest)
+```
+
+Generate coverage report
+```
+$ .build/gen-ccov
+```
+
+Html report left in ``.build/ccov/html/index.html``
 
 ### Nix Build
 
@@ -107,11 +143,19 @@ $ nix-build -A xo-userenv-slow
 Same result as `$nix-build -A xo-userenv`, but builds each package serially
 using `xo-build`.
 
-#### Nix + Vulkan
+#### Nix + SDL2 + Vulkan + ImGui
 
 Currently (Nov 2025) only affects `xo-umbrella2/xo-imgui`.
 
-Non-trivial, because:
+For OSX, imgui works with assistance from motlenvk.
+Build `xo-imgui` with
+
+```
+$ cd xo-umbrella2
+$ nix-shell -A shell4-osx   # see xo-umrbella2/default.nix for impl
+```
+
+For linux and/or wsl build need extra care:
 1. must use host OS for gpu drivers.  nixpkgs has drivers, but they're setup to work from nixos.
 2. want to use nixpkgs for the GPU-independent portion of graphics stack.
 
@@ -125,25 +169,23 @@ These currently setup by hand, so likely to need manual attention on another hos
 An ordinary cmake build may cheerfully use the host-provided graphics stack,
 in return for higher risk of DLL hell.
 
-### Coverage Build
-
-Prepare build
+To build for ubuntu with nvidia gpu:
 ```
-# phase 2
-$ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=${PREFIX} -DCMAKE_BUILD_TYPE=coverage
+$ cd xo-umbrella2
+$ nix-shell -A shell4-nvidia
+# then regular cmake:
+$ cmake -B .build -S . -DXO_ENABLE_VULKAN=1 -DXO_ENABLE_EXAMPLES=1 -DCMAKE_INSTALL_PREFIX=$PREFIX
 ```
 
-Run coverage-enabled unit tests
+To build for wsl:
 ```
-$ (cd .build && ctest)
+$ cd xo-umbrella2
+$ nix-shell -A shell4-wsl
+# then regular cmake:
+$ cmake -B .build -S . -DXO_ENABLE_VULKAN=1 -DXO_ENABLE_EXAMPLES=1 -DCMAKE_INSTALL_PREFIX=$PREFIX
 ```
 
-Generate coverage report
-```
-$ .build/gen-ccov
-```
-
-Html report left in ``.build/ccov/html/index.html``
+Currently not supporting a nix sandbox build for xo-imgui
 
 ## To view docs from WSL
 
diff --git a/docs/install.rst b/docs/install.rst
index 45d5b66f..2e77000f 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -61,10 +61,15 @@ The first phase bootstraps some generated helper scripts used in the second phas
     $ cmake --install .build0
 
     # phase 2 -- build XO, using helpers installed in phase 1.
-    $ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX
+
+    # -DXO_ENABLE_DOCS=1 : builds documentation; or 0 to skip
+    # -DXO_ENABLE_EXAMPLES=1 : builds example; or 0 to skipos
+    # -DXO_ENABLE_VULKAN=1 : builds vulkan-dependent graphics pipeline for imgui; or 0 to skip
+
+    $ cmake -B .build -S . -DCMAKE_INSTALL_PREFIX=$PREFIX -DXO_ENABLE_DOCS=1 -DXO_ENABLE_EXAMPLES=1 -DXO_ENABLE_VULKAN=1
     $ cmake --build .build -j
 
-    # optionally build docs
+    # optionally build docs (requires -DXO_ENABLE_DOCS in phase2 config)
     $ cmake --build .build -- docs
 
     $ cmake --install .build
@@ -100,6 +105,50 @@ See ``Test Coverage Setup`` under ``Development`` below
 Development
 ===========
 
+Environment
+-----------
+
+If nix is available, can use `nix-shell` to get a reproducible development environment for XO work.
+Run `nix-shell` from the top-level `xo-umbrella2` directory.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 20 60 30
+
+   * - command
+     - sufficient for
+     - platform
+   * - `nix-shell -A shell1a`
+     - `cmake -DXO_ENABLE_DOCS=0 -DXO_ENABLE_OPENGL=0 -DXO_ENABLE_VULKAN=0`
+     -
+   * - `nix-shell -A shell1`
+     - `cmake -DXO_ENABLE_DOCS=1`
+     -
+   * - `nix-shell -A shell3`
+     - `cmake -DXO_ENABLE_OPENGL=1`
+     -
+   * - `nix-shell -A shell4-wsl`
+     - `cmake -DXO_ENABLE_VULKAN=1`
+     - wsl2 on windows11
+   * - `nix-shell -A shell4-nvidia`
+     - `cmake -DXO_ENABLE_VULKAN=1`
+     - nvidia GPU on linux
+   * - `nix-shell -A shell4-osx`
+     - `cmake -DXO_ENABLE_VULKAN=1`
+     - mac osx
+
+For example
+
+.. code-block::
+
+    $ cd xo-umbrella2
+    $ nix-shell -A shell4-nvidia
+    $ echo $VK_ICD_FILENAMES
+    /usr/share/vulkan/icd.d/nvidia_icd.json   # point to library to use for nvidia gpu on this host
+    $ which doxygen
+    /home/roland/nixroot/nix/store/cb78mifxvic291rcb2qlbpxgl29f5pzf-doxygen-1.13.2/bin/doxygen
+    # etc.
+
 LSP Setup
 ---------
 
@@ -137,7 +186,6 @@ To build coverage report
 Html report in ``.build/ccov/html/index.html``
 
 
-
 Sphinx Autobuild Setup
 ----------------------