diff --git a/README.md b/README.md
index 5dd52b9..c190411 100644
--- a/README.md
+++ b/README.md
@@ -1,34 +1,95 @@
 # idp.global Swift App
 
-Multiplatform SwiftUI scaffold for the personal `idp.global` companion app on iPhone, iPad, and Mac.
+Multiplatform SwiftUI companion app for `idp.global` across iPhone, iPad, and Mac.
 
-## Included in this first pass
+The current build is a polished preview backed by a mock service layer. It already walks through the core product flow:
 
-- QR-based sign-in flow with a live camera scanner and a seeded mock QR payload fallback
-- Mocked approval inbox for accepting or rejecting identity requests
-- Notification center with local notification permission flow and a test notification trigger
-- Shared app state and mock backend boundary so a real API can be connected later
+- bind a device to an account with a QR payload
+- review and approve identity or access requests
+- track recent security and system events
+- manage notification permissions and send a local test alert
 
-## Open the project
+## Current Product Surface
 
-1. Open [IDPGlobal.xcodeproj](/Users/philkunz/gitea/idp.global-swiftapp/IDPGlobal/IDPGlobal.xcodeproj).
-2. Build the `IDPGlobal` scheme for:
-   - `My Mac`
-   - an iPad simulator
-   - an iPhone simulator
+After pairing, the app opens into a passport-style dashboard with four sections:
 
-## Mock QR payload
+- `Passport`: digital identity summary, trust context, and quick actions
+- `Requests`: approval queue with elevated-risk guidance and inline review
+- `Activity`: timeline of pairing, approval, and system events
+- `Account`: member profile, trusted-device context, and recovery summary
 
-The app seeds this pairing payload on first launch:
+The layout adapts by platform:
+
+- iPhone uses a compact tab-based container
+- iPad and Mac use a split-view workspace with richer side-by-side review
+
+## Pairing Flow
+
+The sign-in flow supports:
+
+- live QR scanning through the camera
+- manual payload paste for testing
+- a seeded preview payload while the real backend is still being wired up
+
+Seeded payload on first launch:
 
 `idp.global://pair?token=swiftapp-demo-berlin&origin=code.foss.global&device=Safari%20on%20Berlin%20MBP`
 
-You can paste it manually or use the "Use Mock QR" action while the backend is still mocked.
+## Mocked Preview Behavior
 
-## Next integration step
+The app currently runs against `MockIDPService`, which seeds:
 
-Replace `MockIDPService` with a live service that:
+- a paired member profile
+- pending and handled approval requests
+- recent notifications and security events
+- simulated incoming requests from the toolbar
 
-- exchanges the QR payload for a session token
-- loads approval requests and notifications from the backend
+This keeps the UI realistic while preserving a clean integration seam for the live backend later.
+
+## Open And Run
+
+1. Open `IDPGlobal.xcodeproj` in Xcode.
+2. Build and run the `IDPGlobal` scheme on:
+   - `My Mac`
+   - an iPhone simulator
+   - an iPad simulator
+
+You can also build from the command line:
+
+```bash
+xcodebuild -project IDPGlobal.xcodeproj -scheme IDPGlobal -configuration Debug -destination 'platform=macOS' build
+```
+
+## Useful Preview Launch Arguments
+
+These launch arguments are already supported by the app model:
+
+- `--mock-auto-pair`: automatically pair with the seeded preview payload on launch
+- `--mock-section=overview`
+- `--mock-section=requests`
+- `--mock-section=activity`
+- `--mock-section=account`
+- `--mock-section=notifications`: opens the activity timeline using a notification-friendly alias
+
+Example:
+
+```text
+--mock-auto-pair --mock-section=requests
+```
+
+## Project Structure
+
+- `Sources/App`: app entry point and shared state in `AppViewModel`
+- `Sources/Features/Auth`: first-run pairing flow and QR scanner UI
+- `Sources/Features/Home`: passport dashboard, requests, activity, notifications, and account surfaces
+- `Sources/Core/Models`: app-facing domain models
+- `Sources/Core/Services`: mock backend boundary and local notification coordination
+
+## Next Integration Step
+
+Replace `MockIDPService` with a live implementation that:
+
+- exchanges the QR payload for a real session
+- loads profile, request, and activity data from the backend
 - posts approval decisions back to `idp.global`
+- syncs notification state with server-side events