docs: document the cmd installer

Describe install.cmd in place of install.ps1: how to run it from the ZIP
or a build tree, its options and limits, the PowerShell-only shortcut,
the user PATH update and what CI verifies.

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

4 files changed, 52 insertions, 36 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index b9805c8..1474fac 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -11,7 +11,7 @@ This file is an index; the detail lives in `AGENTS/ARCH/`.
 | [DRIVER.md](ARCH/DRIVER.md) | `tools/driver/main.cc`: options, multi-file inputs, entry points, output and exit-code rules, PATH/NONE modes |
 | [EMBEDDED_RUNNER.md](ARCH/EMBEDDED_RUNNER.md) | EMBEDDED LLJIT/JITLink runner, MinGW COFF/SEH support, archive loading |
 | [LINKING.md](ARCH/LINKING.md) | Static LLVM/LLD linking, `NativeCompiler`, macOS static LLD helper |
-| [INSTALL.md](ARCH/INSTALL.md) | `install.sh`/`install.ps1`, manual generation, release packaging |
+| [INSTALL.md](ARCH/INSTALL.md) | `install.sh`/`install.cmd`, manual generation, release packaging |
 | [NIGHTLY.md](ARCH/NIGHTLY.md) | `nightly-build.yml` jobs, Bundle packages, macOS LLD/Rust caching, publish rules, package naming |
 | [LAYOUT.md](ARCH/LAYOUT.md) | Source file map (lexer, parser, codegen, CMake, installers), AST conventions |
 
diff --git a/AGENTS/ARCH/INSTALL.md b/AGENTS/ARCH/INSTALL.md
index a1624bd..b3e0c58 100644
--- a/AGENTS/ARCH/INSTALL.md
+++ b/AGENTS/ARCH/INSTALL.md
@@ -26,12 +26,22 @@ listed in `cmake/CompilerPaths.txt`; VERSION is that commit's UTC
 timestamp (`yyyymmdd-hhmmss`) followed by its short ID. Git is only required
 for packaging; recipients can install the extracted archive using just the script.
 
-The Windows `install.ps1` installs `cpsc.exe`, `doc/cpsc.html` and
-`doc/language/**/*.html` for the current user under `%LOCALAPPDATA%\Programs\cpsc` (or `-Prefix`). It appends that directory
-to the user PATH without copying the combined process PATH, and creates a
-per-user Start Menu help shortcut. `-SourceDir` selects the artifact directory;
-`DESTDIR` staging is unsupported on Windows. The script is compatible with
-Windows PowerShell 5.1.
+The Windows `install.cmd` is a pure cmd script (no PowerShell script execution, which school
+machines often block). It installs `cpsc.exe`, `doc/cpsc.html` and
+`doc/language/**/*.html` for the current user under `%LOCALAPPDATA%\Programs\cpsc` (or `--prefix`);
+`--source-dir` selects the artifact directory, `-h`/`--help`/`/?` print usage and unknown
+arguments fail with exit 1. `DESTDIR` staging is unsupported on Windows. Prefixes must be
+absolute and free of `;`, `=`, `!`, `%` and `^` (the PATH update runs with delayed expansion, which would mangle them). The script appends the directory to the user PATH
+(`HKCU\Environment`, preserving REG_SZ/REG_EXPAND_SZ and never using `setx PATH`), without
+copying the combined process PATH; it fails with a manual-edit message if the user PATH
+contains quotation marks or would exceed about 8000 characters. A dummy `setx`/`reg delete`
+pair then triggers an environment refresh. The Start Menu help shortcut
+(`cpsc\cpsc Help.lnk`) is the only PowerShell use, one `powershell -Command` call; if it fails the
+script warns on stderr with the `doc\cpsc.html` path and still exits 0. The script pauses only
+when double-clicked (no arguments and `%cmdcmdline%` contains ` /c `).
+Editing rules for `install.cmd`: ASCII only, CRLF line endings (`.gitattributes` forces
+`eol=crlf`), and no `@NAME@` sequences, since `cmake/Release.cmake` copies it with
+`configure_file(... @ONLY NEWLINE_STYLE CRLF)`.
 The `doc` target uses CMake's `WIN32` target-platform detection: Windows generates
 standalone HTML with inline styles at `build/doc/cpsc.html`; other platforms
 generate `build/doc/cpsc.1`. The section 1 source is `doc/cpsc.1.md`; section 7 sources are
@@ -41,12 +51,12 @@ CONFIGURE_DEPENDS; per-page commands regenerate only changed pages.
 `cmake/ManualLinks.lua` renders cross-references as man names or local HTML links
 (manual source rules: [MAN.md](../MAN.md)).
 Windows `mingw32-make -C build install` builds the HTML manual and invokes
-`install.ps1` through Windows PowerShell with the build directory and
-`CMAKE_INSTALL_PREFIX`. The default Windows prefix is the per-user Programs
+`install.cmd` through `cmd /d /c call` (the explicit `call` behaves the same on CMake 3.x and 4.x)
+with the build directory and `CMAKE_INSTALL_PREFIX`. The default Windows prefix is the per-user Programs
 directory above; explicit prefixes are preserved. Unix still invokes `install.sh`.
 The release target explicitly passes the configured Windows flag to
 `cmake/Release.cmake`, since a standalone CMake script otherwise describes the
-host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `doc/language/**/*.html`, `install.ps1` and
+host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `doc/language/**/*.html`, `install.cmd` and
 `LICENSE` as `build/cpsc-VERSION-Windows-ARCH.zip` using CMake's default Deflate
 compression. Unix retains `.tar.xz`, the POSIX installer and the man pages.
 Generated files and release packages preserve the language category layout.
diff --git a/AGENTS/ARCH/LAYOUT.md b/AGENTS/ARCH/LAYOUT.md
index 2d8f2fd..422d4bb 100644
--- a/AGENTS/ARCH/LAYOUT.md
+++ b/AGENTS/ARCH/LAYOUT.md
@@ -34,7 +34,7 @@
 | `cmake/DependencyPaths.cmake`, `cmake/FindDependency.cmake` | Shared local paths and local-first/system-fallback lookup |
 | `cmake/BuildTools.cmake`, `cmake/LLVMDependencies.cmake` | Compiler/build tool selection and LLVM dependency discovery |
 | `cmake/Manual.cmake`, `cmake/GenerateManual.cmake.in` | Optional manual generation with local-first Pandoc discovery |
-| `install.sh`, `install.ps1`, `cmake/Install.cmake.in`, `cmake/Release.cmake` | Artifact installation and versioned binary release packaging |
+| `install.sh`, `install.cmd`, `cmake/Install.cmake.in`, `cmake/Release.cmake` | Artifact installation and versioned binary release packaging |
 | `cmake/CompilerPaths.txt` | Plain list of compiler source paths; the last commit touching them versions release packages |
 
 AST nodes live in `include/cps/AST.h` (+ `FunctionAST.h`, `FileAST.h`, `TypeAST.h`, `TemplateAST.h`);
diff --git a/doc/install.md b/doc/install.md
index e006429..22c9a7a 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -97,59 +97,65 @@ discovery of an adjacent shared man directory. For explicit lookup, use
 
 Install from an existing MinGW build with:
 
-```powershell
+```bat
 cmake --build build --target install
 ```
 
 This is equivalent to `mingw32-make -C build install`: it generates the HTML
-manual with Pandoc and calls `install.ps1`. The Windows default
+manual with Pandoc and runs `install.cmd` through `cmd.exe`. The Windows default
 `CMAKE_INSTALL_PREFIX` is `%LOCALAPPDATA%\Programs\cpsc`; an explicitly configured
 prefix is preserved. To change it, run
 `cmake -S . -B build -DCMAKE_INSTALL_PREFIX="D:/My Programs/cpsc"` before installing.
 
-You can also call `install.ps1` directly. It installs for the current user without
-administrator rights. Its source directory must contain `cpsc.exe`,
-`doc/cpsc.html` and `doc/language/**/*.html`:
+You can also run `install.cmd` directly. It installs for the current user without
+administrator rights and needs no PowerShell script execution. Its source directory
+must contain `cpsc.exe`, `doc\cpsc.html` and `doc\language\**\*.html`:
 
-```powershell
-powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SourceDir .\build
+```bat
+install.cmd --source-dir build
 ```
 
+In PowerShell, run `.\install.cmd` instead. Quote paths that contain spaces:
+`install.cmd --prefix "D:\My Programs\cpsc"`. Use `--help` for usage.
+
 The default destination is `%LOCALAPPDATA%\Programs\cpsc`: `cpsc.exe` goes in
 that directory, the command manual goes in `doc`, and syntax manuals go in
-`doc/language/function` and `doc/language/keyword`; the overview stays in
-`doc/language`. The command manual links to the language overview and its pages.
-The installer adds the directory to the user PATH and creates Start Menu > cpsc > cpsc Help,
-which opens the manual in the default browser. Open a new terminal afterward;
-existing parent terminals retain their old PATH. Reinstalling does not duplicate
-the PATH entry. Use `-Prefix 'D:\My Programs\cpsc'` for a custom destination,
-or `-Help` for usage. Windows installation does not support `DESTDIR` staging.
-The PowerShell installer targets Windows PowerShell 5.1 or later and has only
-been reviewed statically; Windows installation still needs testing on Windows.
+`doc\language\function` and `doc\language\keyword`; the overview stays in
+`doc\language`. The command manual links to the language overview and its pages.
+The installer adds the directory to the user PATH only (not the system PATH) and
+creates Start Menu > cpsc > cpsc Help, which opens the manual in the default browser.
+Only this shortcut uses PowerShell; if PowerShell is unavailable or blocked, the
+installer prints a warning with the path to `doc\cpsc.html` and still succeeds.
+Open a new terminal afterward; existing parent terminals retain their old PATH
+(sign out and in if `cpsc` is still not found). Reinstalling does not duplicate
+the PATH entry.
+
+Limits: `DESTDIR` staging is unsupported, the prefix must be an absolute path
+without `;`, `=`, `!`, `%` or `^`, and a user PATH that contains quotation marks or is longer than
+about 8000 characters cannot be updated by the installer; add the directory by hand
+in that case. CI runs the installer on Windows; double-click behaviour and the
+Explorer PATH refresh still need a manual desktop check.
 
 ## Windows release packages
 
 Create an installation archive from the configured MinGW build with:
 
-```powershell
+```bat
 cmake --build build --target release
 ```
 
 This is equivalent to `mingw32-make -C build release`. Windows produces
 `build/cpsc-VERSION-Windows-ARCH.zip`, using the same UTC commit version as Unix
 and retaining the configured execution mode. The ZIP contains `cpsc.exe`,
-`doc/cpsc.html`, `doc/language/**/*.html`, `install.ps1` and `LICENSE` under one top-level directory.
+`doc/cpsc.html`, `doc/language/**/*.html`, `install.cmd` and `LICENSE` under one top-level directory.
 It uses CMake's default Deflate compression and needs no additional compression
 tool; packaging requires Git and Pandoc, just as on Unix.
 
-Extract the ZIP using Windows Explorer, open PowerShell in the extracted package
-directory, then run:
-
-```powershell
-powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
-```
+Extract the whole ZIP using Windows Explorer, then double-click `install.cmd` in the
+extracted package directory, or run it from Command Prompt (`install.cmd`) or
+PowerShell (`.\install.cmd`). Double-clicking keeps the window open until a key is pressed.
 
 Recipients need neither CMake, Git nor Pandoc to install. To check installation,
-open a new terminal, run `Get-Command cpsc` and compile a source with
+open a new terminal, run `where cpsc` and compile a source with
 `cpsc test.cps`; open Start Menu > cpsc > cpsc Help to check the manual. Running
 the installer again should leave only one entry for its directory in the user PATH.