docs: troubleshoot stale .nodeenv blocking local tox/install

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Documentation
+- **Developer setup troubleshooting for stale `.nodeenv`** — documented the `nodeenv-version-mismatch` error (an in-repo `.nodeenv/` left over from an older pinned Node.js version) and its fix (`rm -rf .nodeenv` then rebuild), which otherwise blocks `tox` and editable installs locally. Also clarified that `tox` keeps the toolchain fully repo-local (`.tox/`, `.nodeenv/`, `node_modules/` are all git-ignored and regenerated), so nothing is installed into the base/global environment.
+
 ### CI
 - **CI Node bumped 20 → 24** — Node 20 reached end-of-life in April 2026, and the grouped npm updates in #400 raised engine floors (`sass-loader` 17 requires Node ≥22.11). Node 24 is the current active LTS (supported to April 2028). Applies to `ci.yml`, `docs.yml`, and `update-snapshots.yml`; `.nvmrc` and the contributor docs (`CONTRIBUTING.md`, `docs/developer/setup.md`) move to Node 24 in step so local dev matches CI.
 - **Stabilized flaky mobile-chrome visual tests on math-heavy pages** — after the Playwright 1.57→1.60 (Chromium) bump in #400, `math`/`proofs`/`cross-references` full-page screenshots intermittently rendered ~60px shorter than baseline, failing Playwright's dimension check before pixel tolerances apply. `waitForReady` now waits for `document.fonts.ready` and polls until the document height holds steady for 750ms, instead of a fixed 500ms sleep after MathJax typesetting.

docs/developer/setup.md

@@ -77,6 +77,16 @@ See [Testing](testing.md) for detailed information about test fixtures and
 writing new tests.
 :::
 
+### Everything stays repo-local
+
+`tox` keeps the toolchain isolated to this repository — it builds its
+virtualenvs under `.tox/` and installs the package plus its `[test]` extras
+there, never into your base/global Python. The theme's SCSS/JS assets are
+compiled by `sphinx-theme-builder`, which provisions its own Node.js into an
+in-repo `.nodeenv/` (with `node_modules/` for `npm`). All three directories are
+git-ignored, so nothing leaks system-wide and the environment can always be
+rebuilt from scratch by deleting them.
+
 ## Code Style
 
 ### Python
@@ -96,3 +106,28 @@ writing new tests.
 - Modern `@use` / `@forward` syntax (not `@import`)
 - BEM-inspired class naming
 - Maximum 3–4 levels of nesting
+
+## Troubleshooting
+
+### `nodeenv-version-mismatch` when running `tox` or installing
+
+If `tox` (or a `pip install -e .`) fails with something like:
+
+```text
+× The `nodeenv` for this project is unhealthy.
+╰─> There is a mismatch between what is present in the environment (v18.18.0)
+    and the expected version of NodeJS (v20.18.0).
+```
+
+your in-repo `.nodeenv/` is stale — it was provisioned against an older pinned
+Node.js version and never refreshed. `sphinx-theme-builder` rebuilds it
+automatically once it's removed:
+
+```console
+$ rm -rf .nodeenv
+$ tox
+```
+
+The pinned version lives under `[tool.sphinx-theme-builder]` (`node-version`)
+in `pyproject.toml`; deleting `.nodeenv/` is always safe since it is git-ignored
+and regenerated on the next build.