Document mech + map/mission workflows; README folder map + clone warning

- ADDING-A-MECH.md: full workflow for adding a 'Mech chassis (MSL ADD MECH
  touch points, positional Mech IDs, scriptaddmech.xls generator, hardpoints
  in .damage, rebuild/repack/deploy steps)
- ADDING-A-MAP.md: full workflow for maps (MapCreator terrain) vs missions
  (MW4Ed2-authored), .nfo MP registration, user vs stock routes, pitfalls
- CLAUDE.md: reference pointers to both new docs
- README.md: annotated folder map; warning to read RECOVERY.md before cloning

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

README.md

@@ -1,10 +1,64 @@
 # BattleTech: FireStorm — workspace layout
 
+> ⚠️ **Setting up a new machine? Read `RECOVERY.md` BEFORE cloning this repo.**
+> The clone only comes out byte-exact if long paths, `core.autocrlf=false`, and Git LFS are
+> configured *first* — cloning without them silently corrupts line endings, truncates deep
+> VC98/MFC paths, and leaves LFS placeholders instead of the real binaries.
+
 This is the working tree for the FireStorm total-conversion built on the MechWarrior 4
 (Gameleap / GameOS) engine. Only **three** trees feed the build/deploy; everything else is
 output (regenerable), design reference, or archived clutter. See `CLAUDE.md` for the full
 build/runtime reconstruction notes.
 
+## Folder map
+
+```
+C:\VWE\firestorm\
+├─ Gameleap\                       The MW4/Gameleap 5.03 engine + game (the two live trees)
+│  ├─ code\                        ⭐ SOURCE CODE — build mw4\Code\MechWarrior4.dsw in VC6
+│  │  ├─ CoreTech\                 Reusable engine layer: GameOS, MLR renderer, gosFX,
+│  │  │                            GOSScript, Stuff, Network, blade + engine tools
+│  │  ├─ mw4\Code\                 The game itself: MW4 lib (AI, mechlab, HUD, shell),
+│  │  │                            MW4Application (→MW4.exe), MW4GameEd2 (mission editor),
+│  │  │                            scriptstrings/MissionLang (string DLLs), dedicated UI
+│  │  ├─ mw4\Libraries\            mw4-local libs: Adept, stlport (build first), MLR,
+│  │  │                            Compost, ImageLib, gosfx, server, stuff …
+│  │  ├─ mw4\Binaries\             3DS Max export plug-ins (mech/prop .erf pipeline)
+│  │  └─ rel.bin\ pro.bin\         Build OUTPUT: Release (MW4.exe, MW4pro.exe) / Profile
+│  │     arm.bin\ dbg.bin\         (editor MW4Ed2.exe) / Armor / Debug — regenerable
+│  └─ mw4\                         ⭐ GAME DATA source tree (editor also runs here in place
+│     │                            via run-editor.bat; tool exes MapCreator/Tctd/NFOEditor…)
+│     ├─ Content\                  All content sources: Mechs\, Maps\, Missions\, Skies\,
+│     │                            Weapons\, WeaponSubsystems\, Subsystems\, Buildings\,
+│     │                            Vehicles\, Effects\, textures\, Campaigns\, Tables\,
+│     │                            Defines\, ABLScripts\ (mission/AI language),
+│     │                            ShellScripts\ (menu/mechlab UI), *.build manifests
+│     ├─ Resource\                 Packed .mw4 packages (output of `MW4pro -build`) +
+│     │                            Missions\*.nfo (MP registration) + UserMissions\
+│     ├─ hsh\                      Loose 2D art loaded at runtime: mech portraits, MFD
+│     │                            target images, HUD/radar bitmaps, decals, fonts
+│     ├─ Assets\ Stats\            Runtime support data (cursors, world stats)
+│     └─ Movies\ fonts\ Notes\     Cinematics / font sources / dev notes (not deployed)
+├─ build-env\                      ⭐ TOOLCHAIN — self-contained VC6 (VisualStudio6\),
+│  │                               DX 7.0a + DX Media 6 SDKs, stlnative\ headers,
+│  │                               ddrawcompat\ (editor viewport fix), .reg env files,
+│  │                               build/deploy scripts (see below), build logs
+├─ MW4\                            Runnable game deploy (output of deploy-mw4.ps1) —
+│                                  regenerable; copy this to production
+├─ BTFrstrm\                       FireStorm design data: MechInfo_5.04.xls (stat source
+│                                  of truth), scriptaddmech.xls (add-mech row generator)
+├─ Finished HUDS from J&J\         Per-mech HUD source art (MFD + Radar) awaiting
+│                                  integration, ~13 chassis
+├─ _UNUSED\                        Archived clutter — nothing read by the build (EXCEPT
+│                                  worth knowing: Gameleap\EditorDocs\ = original map/
+│                                  terrain/NFO/ABL tutorials)
+├─ CLAUDE.md                       Full build/runtime reconstruction notes (the history)
+├─ README.md                       This file — orientation + fresh-machine restore
+├─ RECOVERY.md                     Disaster-recovery notes
+├─ ADDING-A-MECH.md                Workflow: add a new 'Mech chassis
+└─ ADDING-A-MAP.md                 Workflow: add a new map/mission
+```
+
 ## The folders that matter (build inputs)
 
 | Folder | Role | Notes |