diff --git a/README.md b/README.md
index b53f465ef..222322b03 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,8 @@ In this mode the generated sources use JNI to call native code.
 This mode offers less performance and flexibility than FFM, but it is the most compatible: it works on older JVMs as well as on Android.
 Use it when FFM is not available, or when wide deployment compatibility is your priority. When performance is paramount, prefer FFM.
 
+For Android-specific guidance, see also the [Android documentation](Sources/SwiftJavaDocumentation/Documentation.docc/Android.md).
+
 Required language/runtime versions:
 - **Swift 6.2**, because of dependence on rich swift interface files
 - **JDK 17+**; the generated Java sources target the `javaSourceLevel` setting, which supports 17 through 25 (default 22)
diff --git a/Sources/SwiftJavaDocumentation/Documentation.docc/Android.md b/Sources/SwiftJavaDocumentation/Documentation.docc/Android.md
index 430700083..1c1fc3ac2 100644
--- a/Sources/SwiftJavaDocumentation/Documentation.docc/Android.md
+++ b/Sources/SwiftJavaDocumentation/Documentation.docc/Android.md
@@ -4,6 +4,18 @@ Hints and patterns for using swift-java on Android.
 
 ## Overview
 
+### Main actor and the UI thread
+
+When using Swift from an Android app, work submitted to Swift's main executor
+is not executed by default, so integration with the host environment is needed.
+Without it, asynchronous work that switches to the main actor may stop making
+progress. This applies both to public Swift APIs called directly from Java and
+to uses of the main actor inside a Swift library.
+
+The [swift-android-native](https://github.com/swift-android-sdk/swift-android-native/tree/main#running-work-on-the-android-main-thread)
+implementation is one example of this integration. It can run Swift's main
+actor on Android's UI thread.
+
 ### R8/Proguard Rules
 
 Since swift-java uses JNI and reflection APIs, the R8 optimizer must be told to keep the wrapped types.
diff --git a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaJextract.md b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaJextract.md
index 256028084..ec1af4381 100644
--- a/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaJextract.md
+++ b/Sources/SwiftJavaDocumentation/Documentation.docc/SwiftJavaJextract.md
@@ -67,6 +67,16 @@ public final class SomeModule ... {
 }
 ```
 
+### Main actor in Java-hosted processes
+
+Swift libraries may use the main actor in their public APIs or internally.
+When calling Swift from a Java-hosted process, you may need to integrate
+Swift's main executor with the host's event loop.
+
+Without appropriate integration, work scheduled on the main actor may not
+execute, leaving asynchronous calls incomplete. The required integration
+varies by platform and host configuration. For Android, see <doc:Android>.
+
 ## See Also
 
 - <doc:FeaturesJextract>