docs(skill): add mobile self-test workflow

Author: DIYgod

.agents/skills/mobile-self-test/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: mobile-self-test
+description: Self-test a mobile feature change or bug fix after implementation in `apps/mobile`. Use this whenever the user asks to verify a mobile change, run simulator acceptance, smoke-test a mobile PR, or provide screenshot proof for a mobile fix. This skill decides between prod vs local API mode, starts the local follow-server when needed, builds a release app, uses Maestro only to bootstrap registration for non-auth work, then switches to screenshot-driven visual validation and returns screenshot evidence.
+disable-model-invocation: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+# Mobile Self Test
+
+Validate a mobile change after implementation.
+
+This skill extends `../mobile-e2e/SKILL.md`. Read that skill first for the baseline doctor checks, iOS simulator boot rules, Java/Android SDK setup, and Maestro artifact conventions. Then apply the extra rules in this skill.
+
+## Files that matter
+
+- Reference skill: `../mobile-e2e/SKILL.md`
+- Runner: `apps/mobile/e2e/run-maestro.sh`
+- iOS register flow: `apps/mobile/e2e/flows/ios/register.yaml`
+- Android register flow: `apps/mobile/e2e/flows/android/register.yaml`
+- Shared auth flows: `apps/mobile/e2e/flows/shared/*.yaml`
+- Expo config: `apps/mobile/app.config.ts`
+- Build profiles: `apps/mobile/eas.json`
+- Mobile artifacts: `apps/mobile/e2e/artifacts/`
+- Local server repo: `/Users/diygod/Code/Projects/follow-server`
+
+## Default assumptions
+
+- Prefer **iOS simulator** unless the user explicitly asks for Android or the change is Android-specific.
+- Default to **prod API mode** when the user did not specify a mode.
+- Default to **local API mode** when the task also involves local server changes, backend debugging, or modified files in `/Users/diygod/Code/Projects/follow-server`.
+- Keep `EXPO_PUBLIC_E2E_LANGUAGE=en` unless the user explicitly wants another language. The existing Maestro flows assume English UI.
+
+## Decide API mode first
+
+Use this decision order:
+
+1. If the user explicitly asks for `prod` or `local`, obey that.
+2. Otherwise, if the task depends on local backend changes or local server behavior, use `local`.
+3. Otherwise, use `prod`.
+
+Map the chosen mode into the release build:
+
+- `prod` mode: `EXPO_PUBLIC_E2E_ENV_PROFILE=prod`
+- `local` mode: `EXPO_PUBLIC_E2E_ENV_PROFILE=local`
+
+Do not silently reuse a build from the other mode. Rebuild the release app when switching between `prod` and `local`.
+
+## Always do first
+
+From repo root:
+
+```bash
+cd apps/mobile
+pnpm run e2e:doctor
+pnpm run typecheck
+```
+
+If these fail, stop and report the blocker before attempting simulator work.
+
+## Local server mode
+
+`local` mode requires the local server to be available at `http://localhost:3000`.
+
+Before starting anything, check whether it is already running. Do not start a duplicate server.
+
+```bash
+FOLLOW_SERVER_LOG=/tmp/follow-server-dev-core.log
+
+if pgrep -af "pnpm dev:core" >/dev/null 2>&1 || lsof -nP -iTCP:3000 -sTCP:LISTEN >/dev/null 2>&1; then
+  echo "follow-server already running"
+else
+  (
+    cd /Users/diygod/Code/Projects/follow-server
+    nohup pnpm dev:core >"$FOLLOW_SERVER_LOG" 2>&1 &
+  )
+fi
+
+for _ in $(seq 1 60); do
+  nc -z 127.0.0.1 3000 >/dev/null 2>&1 && break
+  sleep 2
+done
+
+nc -z 127.0.0.1 3000 >/dev/null 2>&1
+```
+
+If the task depends on other local surfaces such as `http://localhost:2233`, call that out explicitly instead of pretending the mobile test fully covers it.
+
+## Release build profiles for self-test
+
+Use release-style builds so the test matches user-facing behavior.
+
+- iOS simulator builds: `PROFILE=e2e-ios-simulator`
+- Android emulator builds: `PROFILE=e2e-android`
+
+Always pair those with the chosen API mode and language:
+
+```bash
+export EXPO_PUBLIC_E2E_ENV_PROFILE=<prod-or-local>
+export EXPO_PUBLIC_E2E_LANGUAGE=en
+```
+
+## iOS workflow
+
+Reuse the simulator selection and boot process from `../mobile-e2e/SKILL.md`.
+
+### Build release simulator app
+
+```bash
+cd apps/mobile/ios
+pod install
+
+PROFILE=e2e-ios-simulator \
+EXPO_PUBLIC_E2E_ENV_PROFILE=<prod-or-local> \
+EXPO_PUBLIC_E2E_LANGUAGE=en \
+xcodebuild -workspace Folo.xcworkspace \
+  -scheme Folo \
+  -configuration Release \
+  -sdk iphonesimulator \
+  -destination 'id=<IOS_UDID>' \
+  clean build
+```
+
+Expected output pattern:
+
+```bash
+~/Library/Developer/Xcode/DerivedData/.../Build/Products/Release-iphonesimulator/Folo.app
+```
+
+### Install app on simulator
+
+```bash
+xcrun simctl install <IOS_UDID> <PATH_TO_Folo.app>
+xcrun simctl launch <IOS_UDID> is.follow
+```
+
+## Android workflow
+
+Reuse the Java and Android SDK setup from `../mobile-e2e/SKILL.md`.
+
+If no emulator is booted yet, start one before installing the APK.
+
+```bash
+emulator -list-avds
+emulator @<AVD_NAME>
+adb wait-for-device
+```
+
+If `apps/mobile/android` does not exist locally, generate it first.
+
+```bash
+cd apps/mobile
+pnpm expo prebuild android
+```
+
+### Build release APK
+
+```bash
+cd apps/mobile/android
+
+PROFILE=e2e-android \
+EXPO_PUBLIC_E2E_ENV_PROFILE=<prod-or-local> \
+EXPO_PUBLIC_E2E_LANGUAGE=en \
+./gradlew clean app:assembleRelease --console=plain
+```
+
+Expected APK path:
+
+```bash
+apps/mobile/android/app/build/outputs/apk/release/app-release.apk
+```
+
+### Install app on emulator
+
+```bash
+adb -s <ANDROID_DEVICE_ID> install -r apps/mobile/android/app/build/outputs/apk/release/app-release.apk
+adb -s <ANDROID_DEVICE_ID> shell monkey -p is.follow -c android.intent.category.LAUNCHER 1
+```
+
+## Choose the auth strategy
+
+This is the core difference from `mobile-e2e`.
+
+### A. Change is **not** related to login or registration
+
+Use the existing automated **registration** flow first to bootstrap a clean logged-in account, then do the real verification visually.
+
+Examples:
+
+- timeline behavior
+- subscription management
+- onboarding content after auth
+- settings pages unrelated to sign-in state
+- player, reader, share, discover, profile editing
+
+Generate a unique test account before running the flow:
+
+```bash
+export E2E_PASSWORD='Password123!'
+export E2E_EMAIL="folo-self-test-$(date +%Y%m%d%H%M%S)@example.com"
+```
+
+#### iOS registration bootstrap
+
+```bash
+cd apps/mobile
+maestro test --format junit --platform ios --device <IOS_UDID> \
+  --debug-output e2e/artifacts/ios/register-bootstrap \
+  -e E2E_EMAIL="$E2E_EMAIL" \
+  -e E2E_PASSWORD="$E2E_PASSWORD" \
+  e2e/flows/ios/register.yaml
+```
+
+#### Android registration bootstrap
+
+```bash
+cd apps/mobile
+maestro test --format junit --platform android --device <ANDROID_DEVICE_ID> \
+  --debug-output e2e/artifacts/android/register-bootstrap \
+  -e E2E_EMAIL="$E2E_EMAIL" \
+  -e E2E_PASSWORD="$E2E_PASSWORD" \
+  e2e/flows/android/register.yaml
+```
+
+After registration succeeds, continue with screenshot-driven visual testing.
+
+### B. Change **is** related to login, registration, logout, session handling, auth validation, or onboarding gates
+
+Do **not** rely on the existing Maestro auth flows for the actual verification. Use a fully visual/manual run instead so the changed UX itself is what gets tested.
+
+Examples:
+
+- register screen changes
+- login screen changes
+- credential validation changes
+- auth toggle changes
+- logout behavior
+- auth/session restoration
+- onboarding shown or hidden based on auth state
+
+For auth-related work:
+
+- create the test account manually through the UI if needed
+- use screenshots after every critical step
+- verify success and error states visually
+- keep a clean record of the exact screen sequence shown to the user
+
+## Screenshot-driven visual testing
+
+Once the app is in the right state, drive the rest of the validation with the visual toolchain available in the current environment. Screenshots are the source of truth for acceptance.
+
+Create a timestamped artifact folder first:
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+ARTIFACT_DIR="$REPO_ROOT/apps/mobile/e2e/artifacts/manual/$(date +%Y%m%d-%H%M%S)-<platform>-<prod-or-local>"
+mkdir -p "$ARTIFACT_DIR"
+```
+
+Capture screenshots after each meaningful checkpoint.
+
+### iOS screenshot command
+
+```bash
+xcrun simctl io <IOS_UDID> screenshot "$ARTIFACT_DIR/<name>.png"
+```
+
+### Android screenshot command
+
+```bash
+adb -s <ANDROID_DEVICE_ID> exec-out screencap -p > "$ARTIFACT_DIR/<name>.png"
+```
+
+Minimum screenshot set for a complete self-test:
+
+1. entry screen before the changed flow
+2. the changed screen or interaction in progress
+3. the final success state or the reproduced bug state
+
+Add more screenshots when the flow has multiple important states.
+
+Do not report success without screenshot evidence.
+
+## What to validate visually
+
+Use the screenshots to confirm at least these points when relevant:
+
+- the correct screen is reached
+- the changed control, copy, or layout is visible
+- loading, empty, error, and success states look correct
+- the operation completes without obvious regressions or blocking dialogs
+- the app is talking to the intended environment (`prod` or `local`)
+
+If the UI or behavior is ambiguous, capture another screenshot instead of guessing.
+
+## Final user-facing output
+
+The final response must include:
+
+- API mode used and why it was chosen
+- platform and simulator/emulator used
+- whether the local server was reused or started, plus log path if started
+- build command used
+- whether auth bootstrap was automated or fully visual
+- concise step-by-step result summary
+- pass/fail conclusion
+- screenshot evidence with absolute file paths
+
+If the client supports local image rendering, attach the key screenshots as images in the final message. Otherwise, list the absolute paths clearly so the user can open them.
+
+## Failure handling
+
+- If doctor, typecheck, build, install, or server startup fails, stop and report the exact failing command.
+- If `local` mode cannot reach the local server, do not silently fall back to `prod`.
+- If the visual flow cannot be completed because the environment lacks the required interaction tooling, report that limitation clearly and still return the screenshots you captured.