docs: guide for single-arch Android APKs (shorebirdtech/shorebird#3402)

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

@@ -459,6 +459,13 @@ tracked in
 can reproduce a rough measurement on your own app by comparing the output of
 `flutter build apk --release` against `shorebird build apk --release`.
 
+### How do you build a smaller APK for a single Android architecture?
+
+Use `--target-platform` on `shorebird release android` to declare which
+architectures to build. A Gradle NDK ABI filter that drops an ABI still listed
+in `--target-platform` is skipped, not treated as an error. See
+[Build a smaller APK for one architecture](/code-push/release/#build-a-smaller-apk-for-one-architecture).
+
 ### When do updates happen?
 
 By default, the Shorebird updater checks for updates on app startup. It runs on

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

@@ -6,6 +6,8 @@ sidebar:
   order: 4
 ---
 
+{/* cspell:words armeabi abiFilters v7a */}
+
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import ArcadeEmbed from '~/components/ArcadeEmbed.astro';
 import { LinkCard } from 'starlight-theme-nova/components';
@@ -88,6 +90,36 @@ command:
 shorebird release android --artifact apk
 ```
 
+### Build a smaller APK for one architecture
+
+By default, `shorebird release android` compiles for three Android ABIs:
+`android-arm` (32-bit ARM / `armeabi-v7a`), `android-arm64` (`arm64-v8a`), and
+`android-x64` (`x86_64`). That produces a larger APK than a Flutter build that
+only packages `arm64-v8a`.
+
+To build for a single architecture, pass `--target-platform` **before** any `--`
+separator:
+
+```sh
+shorebird release android --artifact apk --target-platform android-arm64
+```
+
+Allowed values are `android-arm`, `android-arm64`, and `android-x64`. Pass the
+flag more than once, or as a comma-separated list, to include extra ABIs.
+
+Gradle NDK ABI filters (for example `ndk.abiFilters`) are not a substitute for
+`--target-platform`. If Gradle omits an ABI that is still in
+`--target-platform`, Shorebird skips that architecture instead of failing, and
+the release ships with only the ABIs that actually built. Use
+`--target-platform` to declare the architectures you want — a mismatched Gradle
+filter will not error.
+
+`--target-platform` is a Shorebird flag. Do not put it after `--` — that
+forwards it to `flutter build` and is not applied the same way.
+
+`shorebird patch android` against a single-arch release does not need the flag.
+The patch command skips architectures that were not part of the release.
+
 :::note
 
 By default, `shorebird release` uses the Flutter version bundled within the
@@ -421,6 +453,7 @@ shorebird release windows --flutter-version %flutter_version%
 | `--build-name`       |              | Override the version name (e.g., `1.2.3`).                                                          |
 | `--build-number`     |              | Override the version code / build number (e.g., `42`).                                              |
 | `--artifact`         |              | Android artifact type: `aab` (default) or `apk`.                                                    |
+| `--target-platform`  |              | Android ABIs to compile: `android-arm`, `android-arm64`, `android-x64`. Defaults to all three.      |
 | `--dry-run`          | `-n`         | Build and validate the release but **do not upload** it. Ideal for CI validation.                   |
 | `--obfuscate`        |              | Obfuscate Dart code. Must be used together with `--split-debug-info`.                               |
 | `--split-debug-info` |              | Output debug symbol files to the specified directory when obfuscating.                              |
@@ -498,8 +531,17 @@ using:
 shorebird releases get-apks --release-version 1.0.0+1
 ```
 
-This will download the release artifacts and extract the compatible APK files to
-your machine.
+This downloads the release AAB and builds APK files locally. By default that
+produces a **universal** APK (every ABI in the AAB). Pass `--no-universal` to
+extract one APK per ABI instead:
+
+```sh
+shorebird releases get-apks --release-version 1.0.0+1 --no-universal
+```
+
+If you want a small APK at build time rather than splitting a fat AAB
+afterwards, use `--target-platform` as described in
+[Build a smaller APK for one architecture](#build-a-smaller-apk-for-one-architecture).
 
 ### Delete releases
 

src/content/docs/flutter-concepts/releasing-flutter-apps/android.mdx

@@ -8,7 +8,7 @@ sidebar:
   order: 2
 ---
 
-{/* cspell:words appbundle keytool genkey keyalg keysize proguard */}
+{/* cspell:words appbundle keytool genkey keyalg keysize proguard armeabi */}
 
 Releasing an Android Flutter application requires generating a signed **Android
 App Bundle (AAB)**, configuring your package identifiers, and managing signing
@@ -147,3 +147,14 @@ shorebird release android
 This builds the signed `.aab` bundle and registers the release artifact with the
 Shorebird cloud. Upload the generated `.aab` to Google Play Console as normal.
 When you need to deploy Dart bug fixes later, use `shorebird patch android`.
+
+To produce a smaller APK that contains only one ABI (for example `arm64-v8a`),
+do not use `flutter build apk --split-per-abi` with Shorebird. That Flutter flag
+is not supported. Pass `--target-platform` instead:
+
+```bash
+shorebird release android --artifact apk --target-platform android-arm64
+```
+
+See
+[Build a smaller APK for one architecture](/code-push/release/#build-a-smaller-apk-for-one-architecture).