case 4690 - build docs: pin MkDocs below 2 (Material is incompatible with 2.0); Zensical move on the roadmap

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

devdocs/build/BUILD.md

@@ -39,7 +39,7 @@ that can run this from scratch, use the tool list and install commands in `DEV-V
 | .NET SDK | 10.0.x | Server and launcher |
 | Node.js | **12.22.9 exactly** | Front end. Newer versions break `fibers` |
 | Python | 3.11 | MkDocs |
-| MkDocs + mkdocs-material | current | Customer manual (`pip install mkdocs mkdocs-material`) |
+| MkDocs + mkdocs-material | MkDocs 1.x | Customer manual (`pip install "mkdocs<2" mkdocs-material`). Material for MkDocs does not work with MkDocs 2.0: keep the pin until the docs move to Zensical (see `../modernization/ROADMAP.md`) |
 | Inno Setup | 6.x | Windows installers |
 | 7-Zip | current | Linux zips |
 | Visual Studio | 18 (2026) Community on the dev machine; no VS 2022 installed | QBI only |

devdocs/build/DEV-VM-SETUP.md

@@ -275,7 +275,7 @@ node -v
 ### 4.5 Install MkDocs
 
 ```powershell
-pip install mkdocs mkdocs-material
+pip install "mkdocs<2" mkdocs-material
 ```
 
 Verify:

devdocs/modernization/ROADMAP.md

@@ -37,6 +37,13 @@ In this order, each step tested before the next:
 5. Webpack → Vite
 6. Optional: Options API → Composition API; TypeScript for new files only
 
+## Step F, customer manual build (not part of the current port)
+
+MkDocs 1.x is unmaintained, and Material for MkDocs does not work with MkDocs 2.0 (the
+build prints a warning to that effect since mkdocs-material 9.7). MkDocs is pinned below 2
+(`devdocs/build/BUILD.md`). Later: move the manual and customer docs to Zensical, the
+Material team's successor, and check every page and link after the move.
+
 ## Before step D starts
 
 1. The integration suite passes, apart from the three known server bugs