From 4703243691cdfebd7711181fc6e27b0c91a58ddb Mon Sep 17 00:00:00 2001
From: Matt McKay <mmcky@users.noreply.github.com>
Date: Fri, 19 Jun 2026 13:32:17 +1000
Subject: [PATCH] docs: troubleshoot stale .nodeenv blocking local tox/install
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document the `nodeenv-version-mismatch` error that occurs when the in-repo
`.nodeenv/` is left over from an older pinned Node.js version — it aborts
`tox` and `pip install -e .` before tests can run. The fix is to delete
`.nodeenv/` and let sphinx-theme-builder rebuild it.

Also clarify that `tox` keeps the toolchain fully repo-local (`.tox/`,
`.nodeenv/`, `node_modules/` are all git-ignored and regenerated), so the
test/build environment never touches the base/global Python or Node.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CHANGELOG.md            |  3 +++
 docs/developer/setup.md | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cbf38cf..5157d66 100644
--- a/CHANGELOG.md
+++ b/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.
diff --git a/docs/developer/setup.md b/docs/developer/setup.md
index 80fc97b..d8b85e0 100644
--- a/docs/developer/setup.md
+++ b/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.