| name | ns-android-beta |
| description | Build a NowStack Mobile Android app and upload it to a Play testing track. Always check OS first: macOS may build locally; Windows/Linux must run ns-setup-expo and use EAS cloud. |
Android Beta - NowStack Mobile
Take a NowStack Mobile app from local dev to an installable build on a Play testing track (internal first, then closed). This is the Android beta surface — the equivalent of iOS TestFlight. For the production release (promote to the production track + listing + staged rollout) use ns-android-distribute. The deep Google Play Console (gpc) tool reference is .agents/skills/ns-deploy-android-app/SKILL.md — read it for the upload/track commands. Run the steps here in order.
<platform_build_routing>
Before choosing a build command, detect the OS:
uname -s || node -p "process.platform"
Darwin / darwin: local Android production builds are allowed if Android Studio/SDK/Gradle signing are ready. Prefer the local build path when available; EAS cloud is still allowed if the user explicitly wants it.Linux, win32, or Windows PowerShell: do not attempt local Android production builds. Load/follow .agents/skills/ns-setup-expo/SKILL.md; verify eas-cli, eas whoami, a real easProjectId in site-config.ts, and cd mobile-app && npx expo-doctor. Then use EAS cloud to produce the signed .aab.- If Expo/EAS setup is incomplete on Windows/Linux, stop after fixing
ns-setup-expo; do not continue to Play upload until the account and project link are green.
</platform_build_routing>
Ask once, as a group (the agent cannot create these):
1. **Google Play Developer account** (one-time $25, verified).
2. **A Play Console app** for the package name in `site-config.ts > androidPackage`.
3. **A Play service-account JSON** with the Google Play Developer API enabled (for `gpc`/fastlane upload).
4. **Expo account** logged in and linked (`npx eas-cli@latest whoami`, real `easProjectId`) if building with EAS, and always on Windows/Linux.
```bash
npm run check-setup # easProjectId must be real (Android builds need EAS too)
cd mobile-app && npx tsc --noEmit && npm run lint
uname -s || node -p "process.platform"
```
Confirm `site-config.ts`: `androidPackage`, `payment.productIds.google`, `version`. Package name is permanent once the Play listing exists.
Same prod backend as iOS — if `ns-ios-testflight` already wired prod Convex + `eas.json`, reuse it. Otherwise follow `docs/production-checklist.md` stage 1, and ensure `mobile-app/eas.json > build.production.env` has the **prod** Convex URLs (the build bakes them in).
On Windows/Linux, first complete `ns-setup-expo`, then run the EAS cloud build:
cd mobile-app
npx eas-cli@latest build --platform android --profile production --non-interactive
On macOS, local builds are allowed when the Android SDK/toolchain is ready. Prefer the repo's local EAS build when avoiding cloud credits but still using EAS-managed Android signing:
cd mobile-app
npx eas-cli@latest build --platform android --profile production \
--local --non-interactive --output /tmp/{slug}.aab
EAS manages the Android keystore (first build prompts to generate one; let EAS keep it). Download the .aab artifact when a cloud build reaches FINISHED, or use the explicit /tmp/{slug}.aab path from the local build. Do not use local Gradle production builds on Windows/Linux for this workflow.
Create the managed product / subscription in Play Console with the EXACT id from `site-config.ts > payment.productIds.google`. Activate it before submitting, or purchases fail review.
Use `gpc` (see `ns-deploy-android-app`): authenticate with the service account, `gpc preflight` / `gpc validate`, then upload the `.aab` to the **internal** track for testing:
```bash
gpc preflight "{aab_path}" --fail-on error
gpc publish "{aab_path}" --track internal --validate-only # dry run first
gpc releases upload "{aab_path}" --track internal
gpc status
```
Always validate before a real upload. **Stop here** — promoting beyond internal (closed/production) is `ns-android-distribute`'s job.
Add testers to the internal track in Play Console, install via the opt-in link, and verify the app reaches the prod Convex backend and the purchase flow works. When the build is verified, you're ready for `ns-android-distribute` (production listing, metadata, review, staged rollout).
<failure_modes>
- Upload rejected: package name mismatch → the AAB package ≠
androidPackage in site-config.ts/Play listing.
- App opens but can't reach backend → AAB built before
eas.json had prod Convex URLs; rebuild.
- Purchases fail in review → the Google managed product id doesn't match
payment.productIds.google, or isn't activated.
- Signing/keystore confusion → let EAS own the keystore; don't mix locally-generated and EAS keystores across builds.
- Windows/Linux local build request → run
ns-setup-expo and use EAS cloud; do not try to install Android Studio/Gradle signing for production release builds.
</failure_modes>
<success_metrics>
- Signed
.aab for the correct package, pointing at the prod Convex deployment.
- Uploaded to the internal track and installable by testers; purchase flow tested.
- Hands off to
ns-android-distribute for the production release (listing, Data safety, content rating, staged rollout).
</success_metrics>
