diff --git a/Demo/PowerSyncExample/_Secrets.swift b/Demo/PowerSyncExample/_Secrets.swift
index 8c3d86e..1e1b04e 100644
--- a/Demo/PowerSyncExample/_Secrets.swift
+++ b/Demo/PowerSyncExample/_Secrets.swift
@@ -5,4 +5,4 @@ enum Secrets {
     static let powerSyncEndpoint = "https://your-id.powersync.journeyapps.com"
     static let supabaseURL = URL(string: "https://your-id.supabase.co")!
     static let supabaseAnonKey = "anon-key"
-}
+}
\ No newline at end of file
diff --git a/Demo/README.md b/Demo/README.md
index 70d24e4..3337782 100644
--- a/Demo/README.md
+++ b/Demo/README.md
@@ -14,11 +14,15 @@ Follow this guide to:
 
 ## Configure The App
 
-Open the project in XCode.
+1. Open this directory in XCode.
 
-Open the “_Secrets” file and insert the credentials of your Supabase and PowerSync projects (more info can be found [here](https://docs.powersync.com/integration-guides/supabase-+-powersync#test-everything-using-our-demo-app)).
+2. Open the “_Secrets” file and insert the credentials of your Supabase and PowerSync projects (more info can be found [here](https://docs.powersync.com/integration-guides/supabase-+-powersync#test-everything-using-our-demo-app)).
 
-### Finish XCode configuration
+3. Enable CasePathMacros. We are using SwiftUI Navigation for the demo which requires this.
+
+### Troubleshooting
+
+If you run into build issues, try:
 
 1. Clear Swift caches
 
@@ -32,7 +36,6 @@ rm -rf ~/Library/org.swift.swiftpm
 - Reset Packages: File -> Packages -> Reset Package Caches
 - Clean Build: Product -> Clean Build Folder.
 
-3. Enable CasePathMacros. We are using SwiftUI Navigation for the demo which requires this.
 
 ## Run project
 
diff --git a/README.md b/README.md
index cabd4d3..9355803 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 # PowerSync Swift
 
-The SDK reference for the PowerSync Swift SDK is available [here](https://docs.powersync.com/client-sdk-references/swift).
+This is the PowerSync SDK for Swift clients. The SDK reference is available [here](https://docs.powersync.com/client-sdk-references/swift).
 
 ## Beta Release
 
@@ -47,17 +47,16 @@ Add
     ]
 ```
 
+to your `Package.swift` file and pin the dependency to a specific version. The version is required because the package is in beta.
+
 to your `Package.swift` file and pin the dependency to a specific version. This is required because the package is in beta.
 
 ## Underlying Kotlin Dependency
 
-The PowerSync Swift SDK currently makes use of the [PowerSync Kotlin Multiplatform SDK](https://github.com/powersync-ja/powersync-kotlin) with the API tool [SKIE](https://skie.touchlab.co/) and KMMBridge under the hood to help generate and publish the native Swift SDK. We will move to an entirely Swift native API in v1 and do not expect there to be any breaking changes.
+The PowerSync Swift SDK currently makes use of the [PowerSync Kotlin Multiplatform SDK](https://github.com/powersync-ja/powersync-kotlin) with the API tool [SKIE](https://skie.touchlab.co/) and KMMBridge under the hood to help generate and publish a native Swift package. We will move to an entirely Swift native API in v1 and do not expect there to be any breaking changes. For more details, see the [Swift SDK reference](https://docs.powersync.com/client-sdk-references/swift).
 
 
 ## Migration from Alpha to Beta
 
-* The `PowerSyncDatabase` no longer needs a driver argument and it must be removed.
-* The interface for `PowerSyncDatabase` now uses `PowerSyncDatabaseProtocol` which may require some changes to databases uses.
-* If you were using `__uploadData` and `__fetchCredentials` in your `PowerSyncBackendConnector` you must remove the `__` and update the methods to `uploadData` and `fetchCredentials`.
-* `@MainThread` usage is no longer required and should be removed.
-* Implementing `SuspendTaskWrapper` for database transactions is no longer required and should be removed.
+See these [developer notes](https://docs.powersync.com/client-sdk-references/swift#migrating-from-the-alpha-to-the-beta-sdk) if you are migrating from the alpha to the beta version of the Swift SDK.
+