diff --git a/INSTALLATION.md b/INSTALLATION.md
new file mode 100644
index 0000000..df0360e
--- /dev/null
+++ b/INSTALLATION.md
@@ -0,0 +1,160 @@
+# Installation & Run
+
+Tauri 2 desktop app. The frontend is React 19 + Vite + TypeScript; the backend is Rust + SQLite via sqlx.
+
+---
+
+## 1. Prerequisites
+
+### Common (all platforms)
+- **Node.js ≥ 18** and **npm** (or pnpm / yarn — the lockfile is `package-lock.json`).
+- **Rust** stable, installed via [rustup](https://rustup.rs/):
+  ```bash
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  source "$HOME/.cargo/env"
+  ```
+- **Tauri CLI** (project-local; no global install needed — `npm install` pulls `@tauri-apps/cli`).
+
+### Linux (Debian / Ubuntu / Pop!_OS)
+```bash
+sudo apt update
+sudo apt install -y \
+  build-essential curl wget file \
+  libwebkit2gtk-4.1-dev \
+  libssl-dev \
+  libayatana-appindicator3-dev \
+  librsvg2-dev \
+  libsoup-3.0-dev \
+  pkg-config
+```
+On Ubuntu 22.04 / 24.04 the `4.1` WebKitGTK packages are correct for Tauri 2. If `apt` complains, also try `libjavascriptcoregtk-4.1-dev`.
+
+### Linux (Fedora / RHEL)
+```bash
+sudo dnf install -y \
+  webkit2gtk4.1-devel openssl-devel curl wget file \
+  libappindicator-gtk3-devel librsvg2-devel \
+  libsoup3-devel @development-tools
+```
+
+### Linux (Arch)
+```bash
+sudo pacman -S --needed \
+  webkit2gtk-4.1 base-devel curl wget file \
+  openssl appmenu-gtk-module libayatana-appindicator \
+  librsvg libsoup3
+```
+
+### macOS
+- **Xcode Command Line Tools**:
+  ```bash
+  xcode-select --install
+  ```
+- That's it — Apple ships everything else (WebKit, Core Foundation, etc.).
+
+### Windows
+- **Microsoft C++ Build Tools** (Visual Studio Installer → "Desktop development with C++").
+- **WebView2 runtime** — pre-installed on Windows 11 / recent Win10. Otherwise grab it from <https://developer.microsoft.com/microsoft-edge/webview2/>.
+
+---
+
+## 2. Clone and install
+
+```bash
+git clone <your-repo-url> KML_Tool
+cd KML_Tool/kml_map_tool
+npm install
+```
+
+`npm install` also fetches `@tauri-apps/cli`. Rust dependencies build on the first `tauri dev` / `tauri build`.
+
+---
+
+## 3. Run in development mode
+
+```bash
+npm run tauri dev
+```
+
+What this does:
+- Starts Vite on `http://localhost:1420` (HMR for React).
+- Compiles the Rust backend (`cargo build` — first run takes 5–10 min as sqlx, geo, kml, deck.gl deps cache).
+- Launches the desktop window. Closing the window stops both processes.
+
+**First-run database** — the app creates `markers.db` inside the OS app-data directory:
+- Linux: `~/.local/share/com.kml_map_tool.app/markers.db` (or similar — varies by distro / Tauri identifier).
+- macOS: `~/Library/Application Support/com.kml_map_tool.app/markers.db`
+- Windows: `%APPDATA%\com.kml_map_tool.app\markers.db`
+
+You'll see migrations run silently in the logs. To wipe the DB and start over, use **Reset DB** in the Data section of the app, or delete the file.
+
+### Useful scripts
+```bash
+npm run dev         # frontend only (Vite, no Tauri window) — for browser-only UI testing
+npm run build       # type-check + production frontend build (output: dist/)
+npm run preview     # preview the production frontend (no Tauri)
+npm run tauri dev   # full Tauri dev (frontend + Rust backend + desktop window)
+```
+
+### Rust-only compile check
+From `kml_map_tool/src-tauri`:
+```bash
+cargo check    # fast type-check
+cargo build    # full debug build
+```
+
+### TypeScript check
+From `kml_map_tool`:
+```bash
+npx tsc --noEmit
+```
+
+---
+
+## 4. Build a production binary
+
+```bash
+npm run tauri build
+```
+
+Outputs to `src-tauri/target/release/bundle/`:
+
+- **Linux**: `*.AppImage`, `*.deb`, `*.rpm` (depending on installed packagers; `appimagetool` and `dpkg-deb` need to be on `$PATH` for the corresponding bundle to be produced).
+- **macOS**: `*.app` and `*.dmg`. For a signed/notarised build, set `APPLE_*` env vars per the Tauri docs.
+- **Windows**: `*.msi` (WiX) and `*.exe` (NSIS).
+
+Single-arch native build only — cross-compiling Tauri apps (e.g. macOS → Linux) is not supported out of the box.
+
+---
+
+## 5. First steps after launch
+
+1. **Login screen** — create a user (any username + display name) and click Login. The username is recorded on every audit-log entry.
+2. **Import…** → pick `Fixed assets (JSON)` and point at one of the sample files in the repo (e.g. `Double_Arm_Street_Light_mcw.json`).
+3. The map auto-centers on the first imported asset; pan / zoom to explore.
+4. See [README.md](./README.md) for the full feature tour.
+
+---
+
+## 6. Troubleshooting
+
+### `error: linker 'cc' not found` (Linux)
+`build-essential` (Debian/Ubuntu) or the equivalent dev tools group is missing. See prerequisites above.
+
+### `failed to find webkit2gtk-4.1` (Linux)
+The dev package is missing. On Ubuntu < 22.04 you may have only `4.0` available — Tauri 2 requires `4.1`. Upgrade or build WebKitGTK from source.
+
+### `WebView2 runtime not found` (Windows)
+Install from <https://developer.microsoft.com/microsoft-edge/webview2/>.
+
+### Rust build is incredibly slow / OOM
+The first build pulls hundreds of crates. Add `RUSTFLAGS="-C codegen-units=16"` and use a release machine with ≥ 8 GB RAM. Subsequent builds are incremental and fast.
+
+### `g_object_unref: assertion 'G_IS_OBJECT (object)' failed` on shutdown (Linux)
+Harmless — upstream WebKitGTK / libsoup ref-counting noise. Ignore.
+
+### "Database is locked" errors during heavy bulk operations
+sqlx pool size is 4. If you hit contention, increase `max_connections` in `src-tauri/src/db.rs` and rebuild.
+
+### App window blank / white on Wayland
+Try `WEBKIT_DISABLE_COMPOSITING_MODE=1 npm run tauri dev`.