1 files changed, 92 insertions, 0 deletions
diff --git a/docs/windows-build.md b/docs/windows-build.md
new file mode 100644
index 0000000..88133cb
--- /dev/null
+++ b/docs/windows-build.md
@@ -0,0 +1,92 @@
+# Building MeshBay on Windows
+
+A quick, linear path from a fresh `git clone` to `MeshBay-Setup-<version>.exe`.
+For *why* things are done this way (firewall rules, autostart modes, the
+dependency surface, networking) see [`packaging/win/README.md`](../packaging/win/README.md)
+— this page is deliberately just the steps.
+
+## Prerequisites
+
+Install on the Windows machine that will build the installer:
+
+| Tool | Version | Check |
+|---|---|---|
+| [Node.js](https://nodejs.org) | 22 or newer | `node --version` |
+| Python | 3.12 or newer | `py -3.12 --version` (or `python --version`) |
+| Git | any recent | `git --version` |
+
+Nothing else — no VC++ Redistributable, no separate ffmpeg install. The build
+scripts create their own throwaway Python venv and fetch ffmpeg themselves.
+
+## 1. Clone
+
+```powershell
+git clone https://github.com/<owner>/meshbay.git
+cd meshbay
+```
+
+## 2. Build
+
+```powershell
+cd packages\meshbay-client
+npm run dist:win
+```
+
+This runs [`packaging/win/build-win.ps1`](../packaging/win/build-win.ps1), which:
+
+1. checks Node ≥ 22
+2. `npm ci` and downloads Electron's Chromium
+3. bumps Electron to its latest release (skip with `-NoElectronBump`)
+4. `npm run sync-ui` — copies the SPA from `meshbay-hub/.../static`
+5. runs [`build-node-runtime.ps1`](../packaging/win/build-node-runtime.ps1) —
+   creates a throwaway venv, installs `meshbay-node` + `meshbay-common`,
+   freezes the daemon with PyInstaller, fetches and verifies ffmpeg
+6. `electron-builder --win nsis`
+
+Expect this to take several minutes the first time (Chromium download,
+PyInstaller freeze, ffmpeg fetch). Output:
+
+```
+packages\meshbay-client\dist\MeshBay-Setup-<version>.exe
+```
+
+## 3. Options
+
+```powershell
+# smaller, streaming-less build for local iteration (skips the ~161 MB ffmpeg fetch)
+npm run dist:win -- -SkipFfmpeg
+
+# reuse an already-built node-runtime\ (faster iteration on the Electron side)
+powershell -File ..\..\packaging\win\build-win.ps1 -SkipNodeRuntime
+
+# keep Electron pinned instead of bumping to the latest release
+npm run dist:win -- -NoElectronBump
+```
+
+To rebuild just the frozen daemon on its own:
+
+```powershell
+powershell -File ..\..\packaging\win\build-node-runtime.ps1
+```
+
+## 4. Install and run
+
+Run `MeshBay-Setup-<version>.exe`. It is a **per-user** installer — no admin
+prompt unless you opt into service mode (background daemon that starts at
+boot, before sign-in) or accept the firewall rules, both offered during setup
+and both switchable afterwards from the Node page. Installs to
+`%LOCALAPPDATA%\Programs\MeshBay\`; runtime data lives in
+`%LOCALAPPDATA%\meshbay\`.
+
+## What's not automated yet
+
+- The installer is **unsigned** — Windows SmartScreen will warn on first run
+  (Authenticode signing is planned, not done).
+- No Windows CI runner builds this — it's a manual build today.
+- No genuine clean-machine (bare Windows 11 VM) install has been verified —
+  see `docs/WINDOWS-PORT.md` §5.4 for what has been checked instead.
+
+For everything else — what the installer actually contains, the two autostart
+modes, the firewall rules and why they're scoped the way they are, networking
+across NATs/VMs, and the dependency surface to watch when adding a Python
+package — read [`packaging/win/README.md`](../packaging/win/README.md).