Require reproducible production deploy sources

docs/deployment.md

@@ -19,6 +19,26 @@ bash deploy.sh
 
 `bash sync.sh` remains as a legacy alias for the same flow.
 
+Production deploys require a reproducible Git source tree by default
+(`REQUIRE_CLEAN_GIT=1`). The preflight inspects staged, tracked, and
+deployable untracked files; untracked paths excluded by rsync are ignored.
+The local Vite build may refresh the tracked generated SSR bundle under
+`bootstrap/ssr/`, but source/config/deploy changes made during preparation
+abort before the release is switched. The local Git `HEAD` is captured before
+build and must remain unchanged through rsync.
+
+Run the local-only guard when validating a release without creating a remote
+release or running rsync:
+
+```bash
+bash sync.sh --preflight-only
+```
+
+`--skip-build` is rejected for a clean production deploy unless
+`deploy.cmd` has just completed the Windows build and exported
+`WINDOWS_FRONTEND_BUILT=1`. An explicit `REQUIRE_CLEAN_GIT=0` is reserved for
+non-production/custom workflows and is not the production default.
+
 `deploy.cmd` runs `npm.cmd run build` on Windows first, then enters WSL for rsync/ssh. That is required when the Ubuntu distro cannot execute Windows `.exe` files (`Exec format error` on `powershell.exe`). If WSL interop does work, `bash deploy.sh` can still launch `npm.cmd` through PowerShell. Local Linux `php`/`composer` are not required for a normal deploy; Artisan and Composer run on the production server. `--with-tests` uses WSL `php` when present, otherwise Windows `php.exe`.
 
 This will: