diff --git a/docs/BUILD.md b/docs/BUILD.md
new file mode 100644
index 0000000..67953a7
--- /dev/null
+++ b/docs/BUILD.md
@@ -0,0 +1,119 @@
+# Build & Deploy
+
+## Device
+
+| Field | Value |
+|---|---|
+| Name | Johannes's iPhone |
+| Model | iPhone 12 mini (iPhone13,1) |
+| Device ID | `00008101-0012399122A0001E` |
+| iOS | 26 (wireless pairing via Xcode 16.4) |
+| Bundle ID | `de.vpsj.pi-remote` |
+| Team ID | `KNXX8R3648` |
+
+## Sidecar repo
+
+```
+/Users/jay/.pi/agent/git/git.vpsj.de/jay/pi-remote-control
+```
+
+## 1. Start sidecar (background, needs PTY via tmux)
+
+```bash
+cd /Users/jay/.pi/agent/git/git.vpsj.de/jay/pi-remote-control
+tmux new-session -d -s pi-sidecar -x 220 -y 50 \
+  "pi -nt -ne -ns -np -nc --no-session --offline -e extensions/remote-control --remote-control"
+
+# Check it started (shows URL + token):
+sleep 3 && tmux capture-pane -t pi-sidecar -p | grep -i "remote-control started"
+
+# Kill when done:
+tmux kill-session -t pi-sidecar
+```
+
+The URL + token are printed in the tmux pane, e.g.:
+```
+Remote-control started: http://10.13.37.2:17373/?token=<TOKEN>
+```
+
+Note: the LAN IP (`10.13.37.2`) can change. The token is regenerated each run
+and lives in `~/.pi/remote-control/token`.
+
+## 2. Build for device
+
+```bash
+cd /Users/jay/.pi/agent/git/git.vpsj.de/jay/pi-remote-ios
+
+xcodebuild build \
+  -project piRemote.xcodeproj \
+  -scheme piRemote \
+  -destination "platform=iOS,id=00008101-0012399122A0001E" \
+  DEVELOPMENT_TEAM=KNXX8R3648 \
+  CODE_SIGN_STYLE=Automatic
+```
+
+## 3. Install on device
+
+```bash
+APP=$(find ~/Library/Developer/Xcode/DerivedData/piRemote-*/Build/Products/Debug-iphoneos \
+  -name "piRemote.app" -maxdepth 1 | head -1)
+
+xcrun devicectl device install app \
+  --device 00008101-0012399122A0001E "$APP"
+```
+
+## 4. Launch on device
+
+```bash
+xcrun devicectl device process launch \
+  --device 00008101-0012399122A0001E \
+  de.vpsj.pi-remote
+```
+
+## 5. Pair the iOS app with the sidecar
+
+Run on Mac (sidecar must be running):
+```bash
+node /Users/jay/.pi/agent/git/git.vpsj.de/jay/pi-remote-control/extensions/remote-control/cli/index.js pair
+```
+
+Scan the QR code with the iPhone app. App stores the bearer token in Keychain
+and connects automatically.
+
+## 6. One-liner: build + install + launch
+
+```bash
+cd /Users/jay/.pi/agent/git/git.vpsj.de/jay/pi-remote-ios && \
+xcodebuild build \
+  -project piRemote.xcodeproj -scheme piRemote \
+  -destination "platform=iOS,id=00008101-0012399122A0001E" \
+  DEVELOPMENT_TEAM=KNXX8R3648 CODE_SIGN_STYLE=Automatic 2>&1 | grep -E "error:|SUCCEEDED|FAILED" | grep -v note: && \
+APP=$(find ~/Library/Developer/Xcode/DerivedData/piRemote-*/Build/Products/Debug-iphoneos -name "piRemote.app" -maxdepth 1 | head -1) && \
+xcrun devicectl device install app --device 00008101-0012399122A0001E "$APP" && \
+xcrun devicectl device process launch --device 00008101-0012399122A0001E de.vpsj.pi-remote
+```
+
+## APNs key
+
+```
+~/.local/share/pi-remote/apns/AuthKey_285C2X4689.p8
+Key ID:  285C2X4689
+Team ID: KNXX8R3648
+```
+
+## Xcode version
+
+Xcode 16.4 (`/Applications/Xcode-16.4.0.app`) — last Intel-compatible version.
+Device runs iOS 26; wireless pairing works despite version mismatch.
+Direct CLI deploy works via `xcrun devicectl`.
+
+## Simulator (for UI dev without device)
+
+```bash
+# iPhone 16 Pro simulator
+xcodebuild build \
+  -project piRemote.xcodeproj \
+  -scheme piRemote \
+  -destination "platform=iOS Simulator,id=C147BAB0-6644-477E-8E9E-77E7D5D5092B" \
+  CODE_SIGNING_ALLOWED=NO
+```