diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx
index d54804e0..1c8f747e 100644
--- a/src/content/docs/code-push/faq.mdx
+++ b/src/content/docs/code-push/faq.mdx
@@ -294,6 +294,17 @@ the latest version from the server if needed.
 If you have a use case for code push with Fluter web, we'd
 [love to know](mailto:contact@shorebird.dev)!
 
+### Does Shorebird work on the iOS Simulator?
+
+No. Shorebird's code push does not work on the iOS Simulator. On physical iOS
+devices, Shorebird uses a custom ARM interpreter to run patched Dart code. The
+iOS Simulator runs on your Mac's native architecture (x86_64 or Apple Silicon),
+which is fundamentally different from the ARM environment on real iOS devices.
+Because the patching mechanism is built specifically for the iOS device runtime,
+it cannot function in the simulator.
+
+To test patches on iOS, you will need to use a physical iOS device.
+
 ## Technical Details
 
 ### What does the Shorebird updater store on disk?
diff --git a/src/content/docs/code-push/guides/flavors/android.mdx b/src/content/docs/code-push/guides/flavors/android.mdx
index 54762056..0c8e0b15 100644
--- a/src/content/docs/code-push/guides/flavors/android.mdx
+++ b/src/content/docs/code-push/guides/flavors/android.mdx
@@ -94,6 +94,14 @@ buildTypes {
 </TabItem>
 </Tabs>
 
+:::caution
+
+The `applicationIdSuffix` property is optional. If you use services that depend
+on a consistent package name (e.g., Firebase), removing `applicationIdSuffix`
+may be necessary to avoid configuration issues.
+
+:::
+
 Lastly, edit `android/app/src/main/AndroidManifest.xml` to use the
 `applicationLabel` so that we can differentiate the two apps easily: