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>

3 files changed, 21 insertions, 11 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`);