From 7ecf843181ac17049c0ba3c056f1a9f5aa783c96 Mon Sep 17 00:00:00 2001
From: Cyd <cyd@falloutshelterarcade.com>
Date: Fri, 26 Jun 2026 10:40:23 -0500
Subject: [PATCH] update readme

---
 README.md   | 34 ++++++++++++++++++++++++++++++++++
 RECOVERY.md |  2 +-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 16beaea6..ca4d3fa7 100644
--- a/README.md
+++ b/README.md
@@ -46,3 +46,37 @@ Moved here to reduce confusion. Safe to delete once you're comfortable. Contents
 1. Compile code: VC6 build `Gameleap\code\mw4\Code\MechWarrior4.dsw` → `rel.bin\` / `pro.bin\`.
 2. Deploy game: `build-env\deploy-mw4.ps1` → `MW4\` (packs resources, assembles, optimizes).
 3. (Optional) Install editor: `build-env\deploy-editor.ps1` → runs in place from `Gameleap\mw4` (`run-editor.bat`).
+
+## On a fresh Windows machine
+1. Install **Git for Windows** (includes Git LFS) — or Git + `git-lfs` separately.
+2. Enable long paths **before** cloning (this tree has deep VC98/MFC paths > 260 chars):
+   ```
+   git config --global core.longpaths true
+   git config --global core.autocrlf false
+   git lfs install
+   ```
+   (Also enable the OS setting: `HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1`.)
+3. Clone to the same location so the absolute paths baked into the toolchain config resolve:
+   ```
+   git clone https://gitea.mysticmachines.com/VWE/firestorm.git C:\VWE\firestorm
+   ```
+   `git clone` pulls LFS objects automatically. If any are missing: `cd C:\VWE\firestorm && git lfs pull`.
+
+## After restore — make it buildable / runnable
+- **Build toolchain (VC6):** import the registry config (ELEVATED), per `build-env\README.md`:
+  ```
+  reg import C:\VWE\firestorm\build-env\vc6-hklm-registration.reg
+  reg import C:\VWE\firestorm\build-env\vc6-directories.reg
+  ```
+  Then build `Gameleap\code\mw4\Code\MechWarrior4.dsw` (see `CLAUDE.md` STEP 1/3), or just use the
+  already-mirrored `Gameleap\code\rel.bin` / `pro.bin` binaries.
+- **Run the game:** `build-env\deploy-mw4.ps1` reassembles `C:\VWE\firestorm\MW4` and applies the Win11
+  DirectDraw compat shim; or run the already-mirrored `C:\VWE\firestorm\MW4\MW4.exe` after re-applying the
+  shim (AppCompat is keyed on exe *path*, so a new machine needs it re-set — the deploy script does this).
+- **Editor:** `Gameleap\mw4\run-editor.bat` (installed in place; see `CLAUDE.md` STEP 9).
+
+## Notes
+- `core.autocrlf=false` — line endings are preserved byte-for-byte; keep it that way.
+- The mirror includes machine-specific bits (registry exports, deploy AppCompat). They restore the
+  *files*, but registry/AppCompat state must be re-imported on the new machine (steps above).
+- See `CLAUDE.md` for the full build/runtime reconstruction history and `README.md` for the layout.
\ No newline at end of file
diff --git a/RECOVERY.md b/RECOVERY.md
index 98ae9c04..0815acdf 100644
--- a/RECOVERY.md
+++ b/RECOVERY.md
@@ -15,7 +15,7 @@ Large binaries are stored in **Git LFS**. A single clone reconstitutes a working
    (Also enable the OS setting: `HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled = 1`.)
 3. Clone to the same location so the absolute paths baked into the toolchain config resolve:
    ```
-   git clone <gitea-url>/firestorm.git C:\VWE\firestorm
+   git clone https://gitea.mysticmachines.com/VWE/firestorm.git C:\VWE\firestorm
    ```
    `git clone` pulls LFS objects automatically. If any are missing: `cd C:\VWE\firestorm && git lfs pull`.