docs(toolchain): clarify MINGW64 LLVM and Clang 23 setup

Select the MINGW64 compiler executables with explicit Windows paths and
add version checks for installed Clang and downloaded LLVM packages.
Document Windows PATH requirements and platform-specific C++ driver names.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2 files changed, 38 insertions, 3 deletions

diff --git a/doc/build.md b/doc/build.md
index c8345a3..1af8a81 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -80,6 +80,29 @@ pacman -S --needed \
   mingw-w64-x86_64-clang
 ```
 
+Confirm that both installed compilers report major version 23:
+
+```bash
+/mingw64/bin/clang.exe --version
+/mingw64/bin/clang++.exe --version
+```
+
+The [MINGW64 Clang package](https://packages.msys2.org/packages/mingw-w64-x86_64-clang)
+and [LLVM package](https://packages.msys2.org/packages/mingw-w64-x86_64-llvm)
+currently provide 23.1.3. MSYS2 keeps these package names unversioned; its
+compiler executables are `clang.exe` and `clang++.exe`, not `clang-23.exe` or
+`clang++-23.exe`. CMake rejects another major version even when the package
+name is unchanged. MINGW64 Clang uses the GNU linker and C++ library supplied
+by its package dependencies; cpsc itself is compiled with Clang 23.
+
+Before downloading LLVM, confirm that these repository packages' `Version`
+fields all start with `23.`:
+
+```bash
+pacman -Si mingw-w64-x86_64-llvm \
+  mingw-w64-x86_64-llvm-libs mingw-w64-x86_64-llvm-tools
+```
+
 Recommended dependency downloads to the project build directory:
 
 ```bash
@@ -150,10 +173,17 @@ MSYS2 MINGW64:
 ```bash
 cmake -S . -B build -G "MinGW Makefiles" \
   -DCPSC_RUN_MODE=EMBEDDED -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
+  -DCMAKE_C_COMPILER="$(cygpath -m /mingw64/bin/clang.exe)" \
+  -DCMAKE_CXX_COMPILER="$(cygpath -m /mingw64/bin/clang++.exe)"
 mingw32-make -C build -j4
 ```
 
+These explicit paths select the MINGW64 compilers checked above. `cygpath -m`
+converts the MSYS2 paths for native Windows CMake. Configuration must report
+Clang 23 for both compilers and `Found LLVM 23.x` for the selected development
+libraries. Use the MINGW64 packages throughout; do not mix CLANG64 or UCRT64
+libraries into this build.
+
 macOS:
 
 ```bash
@@ -196,6 +226,11 @@ MSYS2 MINGW64:
 export PATH="$PWD/build/deps/root/mingw64/bin:$PATH"
 ```
 
+In this shell, `lli.exe --version` should identify LLVM 23. `cpsc -r` validates
+the same PATH executable automatically before compiling the source. When
+running from PowerShell or Command Prompt, add the Windows path to this `bin`
+directory to that terminal's PATH so its DLLs can also be found.
+
 macOS:
 
 ```bash
diff --git a/doc/cpsc.1.md b/doc/cpsc.1.md
index 362d48b..063e2c1 100644
--- a/doc/cpsc.1.md
+++ b/doc/cpsc.1.md
@@ -66,11 +66,11 @@ Save IR and run it:
 cpsc test.cps -r -o result.ir
 ```
 
-Build a native program with a C++ linker so the exception runtime is linked:
+Build a native program with Clang 23's C++ driver so the exception runtime is linked. Use `clang++` from the LLVM 23 installation; Debian/Ubuntu also provides the versioned name `clang++-23`. MSYS2 MINGW64 and Homebrew use the unversioned name.
 
 ```sh
 cpsc test.cps -o test.ll
-clang++-23 test.ll -o test
+clang++ test.ll -o test
 ./test
 ```