diff --git a/Sources/App/piRemoteApp.swift b/Sources/App/piRemoteApp.swift
index 25c4d0a..fc0614e 100644
--- a/Sources/App/piRemoteApp.swift
+++ b/Sources/App/piRemoteApp.swift
@@ -1,10 +1,12 @@
 import SwiftUI
+import UIKit
 import UserNotifications
 
 @main
 struct piRemoteApp: App {
     @StateObject private var appState = AppState.shared
     @StateObject private var notificationDelegate = NotificationDelegate.shared
+    private let pairingService = PairingService()
 
     var body: some Scene {
         WindowGroup {
@@ -14,6 +16,29 @@ struct piRemoteApp: App {
                     notificationDelegate.setup()
                     UIApplication.shared.registerForRemoteNotifications()
                 }
+                .onOpenURL { url in
+                    handlePairingURL(url)
+                }
+        }
+    }
+
+    /// Handle `pi-remote://...` deep links — dev / simulator convenience pairing.
+    private func handlePairingURL(_ url: URL) {
+        guard let parsed = try? PairingService.parseQR(url.absoluteString) else { return }
+        Task { @MainActor in
+            do {
+                let credential = try await pairingService.exchange(
+                    host: parsed.host,
+                    port: parsed.port,
+                    pairingToken: parsed.pairingToken,
+                    fingerprint: parsed.fingerprint,
+                    name: parsed.name,
+                    deviceName: UIDevice.current.name
+                )
+                appState.didPair(credential: credential)
+            } catch {
+                print("[pairing] deep-link exchange failed: \(error)")
+            }
         }
     }
 }
diff --git a/docs/BUILD.md b/docs/BUILD.md
index d2bce3a..546b470 100644
--- a/docs/BUILD.md
+++ b/docs/BUILD.md
@@ -119,11 +119,33 @@ Direct CLI deploy works via `xcrun devicectl`.
 
 ## Simulator (for UI dev without device)
 
+**Preferred simulator: iPhone 12 mini (matches the physical test device).**
+Sim UUID: `062F8F0A-B3E5-4A4B-BC8A-B01E98CF27F2`
+
 ```bash
-# iPhone 16 Pro simulator
+SIM=062F8F0A-B3E5-4A4B-BC8A-B01E98CF27F2
+xcrun simctl boot $SIM
+open -a Simulator
+
 xcodebuild build \
   -project piRemote.xcodeproj \
   -scheme piRemote \
-  -destination "platform=iOS Simulator,id=C147BAB0-6644-477E-8E9E-77E7D5D5092B" \
+  -destination "platform=iOS Simulator,id=$SIM" \
   CODE_SIGNING_ALLOWED=NO
+
+APP=$(find ~/Library/Developer/Xcode/DerivedData/piRemote-*/Build/Products/Debug-iphonesimulator -name "piRemote.app" -maxdepth 1 | head -1)
+xcrun simctl install $SIM "$APP"
+xcrun simctl launch $SIM de.vpsj.pi-remote
+```
+
+### Deep-link pairing in simulator
+
+The app handles `pi-remote://` URLs via `.onOpenURL` for dev convenience:
+
+```bash
+PAIR_URL=$(curl -s "http://10.13.37.2:17373/pair-qr?token=$TOKEN&format=url" | grep -oE 'pi-remote://[^[:space:]]+' | head -1)
+xcrun simctl openurl $SIM "$PAIR_URL"
+# Tap "Open" in the iOS confirm dialog — use cliclick to script it:
+# (window content rect: pos (591,124), size (323,700))
+cliclick c:778,495   # Open button on iPhone 12 mini
 ```