docs: document Shorebird with long-running Android background processes (shorebirdtech/shorebird#2396)

src/content/docs/code-push/faq.mdx

@@ -535,7 +535,9 @@ in `--target-platform` is skipped, not treated as an error. See
 By default, the Shorebird updater checks for updates on app startup. It runs on
 a background thread and does not block the UI thread. Any updates will be
 installed while the user is using the app and will be applied the next time the
-app is restarted.
+process restarts. See
+[How do you use Shorebird with a long-running Android background process?](#how-do-you-use-shorebird-with-a-long-running-android-background-process)
+if a background process keeps the app alive.
 
 It is also possible to run the Shorebird updater manually using
 [package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push),
@@ -545,6 +547,35 @@ push notification.
 See [Update Strategies](/code-push/update-strategies) for more information about
 how to configure this behavior.
 
+### How do you use Shorebird with a long-running Android background process?
+
+Shorebird applies a downloaded patch the next time the process starts, not when
+an Activity is recreated.
+
+A foreground service (for example
+[flutter_background_geolocation](https://github.com/transistorsoft/flutter_background_geolocation))
+keeps the process alive after the user swipes the app out of the recent-apps
+list. That swipe is not a process restart, so bringing the UI back still runs
+the previous Dart code.
+
+To receive patches while the process stays alive:
+
+1. Check for and download patches while the process is running with
+   [package:shorebird_code_push](https://pub.dev/packages/shorebird_code_push).
+   Default automatic updates only run on process start.
+2. Detect the staged patch. `checkForUpdate()` returns
+   `UpdateStatus.restartRequired` once a patch is downloaded and waiting, and
+   `readNextPatch()` returns it. Use that to prompt the user to restart at a
+   point that suits your app.
+3. Apply the patch with a real process restart. Stopping the foreground service
+   and then swiping the app away is enough, as is waiting until the OS kills the
+   process.
+
+While testing, you can force a restart with **Settings → Apps → Force stop**.
+
+Recreating the Flutter engine without killing the process is not a supported way
+to apply a patch. See [Update Strategies](/code-push/update-strategies).
+
 ### What information is sent to Shorebird servers?
 
 Although Shorebird connects to the network, it does not send any personally

src/content/docs/code-push/troubleshooting.mdx

@@ -98,6 +98,27 @@ Sending patch check request: PatchCheckRequest {
 
 Only patches created for this release version will be compatible with your app.
 
+**The app's process is still running because of a foreground service.**
+
+If the app runs a foreground service or other long-running background work,
+swiping it from the recent-apps list does not kill the process. Shorebird loads
+the patch on the next process start.
+
+**How to tell if this is the problem**
+
+The process ID does not change when you swipe the app away. Run
+`adb shell pidof <your.package.name>` before and after swiping: if it prints the
+same PID both times, the process never died and no patch will be applied.
+
+From Dart, the equivalent signal is `checkForUpdate()` returning
+`UpdateStatus.restartRequired`, or `readNextPatch()` reporting a higher patch
+number than `readCurrentPatch()`.
+
+**How to fix it**
+
+Force-stop the app, or stop the service first, then relaunch. See
+[How do you use Shorebird with a long-running Android background process?](/code-push/faq/#how-do-you-use-shorebird-with-a-long-running-android-background-process).
+
 ## `Your app contains asset changes` warning when creating a patch
 
 The `shorebird patch` command will print a warning if it detects changes to