@1aboveio/skills 0.0.0-stage → 1.0.1

package/skills/app-dev/android-foundation/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: android-foundation
+description: "Prove an Expo / React Native app on a native Android emulator, and fix it when that proof fails. Use before you fix and re-run or re-dispatch a failed Android CI job (`gh workflow run android.yml`, `gh run rerun`): a re-run is not a debugger, so reproduce the failing journey checkpoint off CI first. Also use when a UiAutomator journey or its Python harness tests fail (a CHECK/FAIL line, a wait that timed out, a control not found, adb offline, a lost Metro bridge, a fixture failing on the runner), to build the debug APK and run the device journey, to set up a fresh Android workspace (SDK/NDK/JDK, Gradle caches, private AVD, disposable PostgreSQL), or to add the emulator job to CI. NOT for workflow YAML, CI speed or runner design (github-actions), browser tests (e2e-test), iOS (ios-foundation), plain Jest component tests, or signing and store release."
+release-version: 0.38.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Android foundation
+
+Take a native Expo / React Native Android workspace from a fresh checkout to a passing
+device journey, then record the evidence. Use the repo's existing build scripts, native
+project, device harness and journey wrapper. For CI, add one job to the repo's `ci.yml`
+from the template; do not write a separate release runbook.
+
+Pick the mode first:
+
+- **Setup proof:** a new workspace or CI job, a toolchain, dependency, native or harness
+  change, or a broken build-to-device path. Run every stage and write the
+  [evidence record](#evidence-record).
+- **Feature work:** proving a product change on the emulator in a workspace already set
+  up. Follow [Feature work](#feature-work) and report only the journey result.
+
+## Routing
+
+| Step | Read |
+| --- | --- |
+| Shell snippets for every stage below | [references/setup.md](references/setup.md) |
+| Stages 6–8 in one command | [scripts/device-run.sh](scripts/device-run.sh) |
+| Adding the Android job to CI | [references/ci.md](references/ci.md), template [assets/android-ci-job.yml](assets/android-ci-job.yml) |
+| Proving a product change on the emulator | [Feature work](#feature-work) |
+| A stage failed | [Triage](#triage), then [references/gotchas.md](references/gotchas.md) |
+| Writing up setup proof | [Evidence record](#evidence-record) |
+
+## Rules
+
+- Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
+  another checkout, and never symlink another worktree's `node_modules`.
+- Tool shells keep no variables, functions or traps between calls. Write the environment
+  to `.cache/android-env.sh` once and source it at the start of every command. Run stages
+  6–8 as one `scripts/device-run.sh` command, never as separate calls.
+- Keep every cache private to the worktree under `.cache/`: Gradle home, Android user home,
+  AVD home, `TMPDIR`, npm, node-gyp and pnpm store. Keep them between runs.
+- Read toolchain versions from the repo: the root `packageManager` and `engines`, the
+  native Gradle config, and the CI preflight. The repo is the source of truth, not this skill.
+- Check that every required SDK component (platform, build-tools, NDK, CMake,
+  platform-tools, emulator, system image) is already installed. If one is missing, stop and
+  provision it separately. Never upgrade or install into a shared SDK during a journey;
+  build with `-Pandroid.builder.sdkDownload=false`.
+- Install with `--frozen-lockfile`. Do not routinely run `clean`, reinstall dependencies or
+  run `expo prebuild`. The native project is tracked, and prebuild needs a reviewed native
+  change.
+- Build every configured ABI for setup proof and release acceptance. An x86_64-only CI
+  APK only proves the emulator ABI. For feature work, the emulator ABI is enough unless the
+  change touches native code or ABI configuration.
+- A debug APK needs Metro. A successful export or build does not prove the app works on
+  a device. Only the device journey does.
+
+## Stages
+
+Run them in this order. Stop at the first failure and triage it.
+
+1. **Checkout and environment.** Add the worktree and export the private cache paths,
+   `JAVA_HOME` (JDK 17), `ANDROID_HOME` and `ANDROID_SDK_ROOT`. Print the versions of
+   node, pnpm, java, python3, adb and the emulator. Assert that each SDK component
+   directory exists. Read the journey wrapper and device harness for the names they expect:
+   the venv path, the port variables, the database variables and the database-name prefix
+   the harness accepts.
+2. **Install and check.** Run a frozen install, the app's unit tests, typecheck, and
+   `expo export --platform android` with a placeholder `EXPO_PUBLIC_API_URL`. Create a
+   Python venv for UI automation at the path the journey wrapper reads, and pin the
+   `uiautomator2` version the harness expects.
+3. **Gradle dependencies.** Pick one:
+   - Seed: `rsync --ignore-existing` only `caches/modules-2/files-2.1/` from a trusted
+     Gradle home, excluding `*.lock`, `*.lck` and `*.tmp`. Never share writable caches,
+     metadata, credentials or APKs.
+   - Proxy: a private Gradle home does not inherit `~/.gradle/init.d`. Install the proxy's
+     init script into `$GRADLE_USER_HOME/init.d/` and export a route for every repository
+     the build uses, JitPack included. Ping the proxy first.
+   - Neither: build against upstream and expect a long cold build.
+   If the opted-in proxy fails, treat it as an error. Never fall back to direct downloads
+   and never disable TLS checks. The proxy covers Gradle Maven repositories only. Route the
+   Gradle wrapper ZIP and pnpm as the repo's CONTRIBUTING says.
+4. **Build.** Run the repo's Android build script with `--max-workers=2
+   -Dorg.gradle.parallel=false -Pandroid.builder.sdkDownload=false --console=plain
+   --info`, keeping the log. For setup proof, hash the APK and list its `lib/<abi>/`
+   entries.
+5. **Owned emulator.** Create a new private AVD in `$ANDROID_AVD_HOME` by copying only
+   `config.ini` from an installed AVD. Never copy its user data or snapshots. Check that
+   `image.sysdir.1` points to an installed, host-compatible image, and set `target` to
+   match it. Writing `config.ini` from scratch needs the hardware keys:
+   [gotchas](references/gotchas.md#a-hand-written-avd-misses-the-screen). Give the guest
+   4 GB: replace any `hw.ramSize` with `hw.ramSize=4096` (`device-run.sh` also passes
+   `-memory 4096`). At 2 GB, the usual `avdmanager` value, adb drops mid-journey ([gotchas](references/gotchas.md#the-adb-transport-drops-mid-journey)).
+6. **Register cleanup before starting anything.** `device-run.sh` installs the `EXIT`
+   trap and the `INT`/`TERM` handlers first.
+7. **Start resources.** The script refuses an emulator console port outside 5554–5584
+   (adb scans only that range) and any busy port, starts the ADB server, then the emulator
+   (PID recorded) and `postgres` (`--cidfile`, random loopback port), and waits for
+   `sys.boot_completed=1` and `pg_isready` with a time limit on every command.
+8. **Journey.** The script hands the harness a database named with its accepted prefix and
+   runs the journey wrapper. Expect every scenario's `PASS` marker, plus screenshots, the
+   backend log and the Metro log.
+
+## Owned-resource cleanup
+
+- Clean up only what this run started: the emulator child PID, the container ID from the
+  CID file, and the named database. Signal the PID with `TERM`, wait up to 10 seconds, then
+  `KILL`. Then `wait` for it and confirm nothing is left. Count wait status 0 or 143 (ended
+  by your `TERM`) as a clean stop; count a needed `KILL` or any other status as a failure.
+- Never use `adb kill-server`, `adb -s <serial> emu kill`, broad `pkill`, or
+  `docker system prune`. An ADB serial can be reused by another process; a PID you own
+  cannot.
+- Give every startup, readiness and cleanup command a 30-second limit that kills the
+  command's whole process group. Treat exit 124 (timeout) as a terminal failure, not as
+  "not ready yet".
+- Preserve the stage's original non-zero exit status even when cleanup succeeds. Print
+  `original_stage_exit=<n> cleanup_exit=<n>`.
+- After a `SIGKILL` or a host crash, the trap cannot run. Remove only this run's recorded
+  PID and container ID by hand, and keep the failure logs.
+- Point the database URL only at the disposable loopback container. Never at development,
+  production or another worker's database.
+- Expo may rewrite `android/tsconfig.json` or delete `android/expo-env.d.ts` while it runs.
+  Inspect those changes and restore them before you commit.
+
+## Triage
+
+Name the earliest stage that failed. In CI, that is the first failed step. If the same
+journey passed on another run of the same commit, suspect the run or the journey before
+the product.
+
+| Stage | Typical signal |
+| --- | --- |
+| Prerequisites / install | missing SDK directory, wrong JDK, lockfile drift |
+| Harness unit tests (CI, before the APK) | a harness test fails on host state its fixture should fake (`requires 2 GiB reserve`) |
+| Export / APK | Metro bundling error, Gradle compile or dependency-resolution error |
+| Gradle network | Maven download or TLS-handshake errors on a cold build: fix routing, not code |
+| Emulator boot / ADB | `sys.boot_completed` never reaches 1, device offline, exit 124 |
+| Device to Metro | red box, "unable to load script", missing `adb reverse` mapping |
+| Device to Metro, mid-journey | a screen's first Metro asset fails (`Unable to download asset from url: http://127.0.0.1:8081/assets/…`) while API calls still succeed |
+| Backend / Login | backend log errors, verification code not found in the database |
+| Backend tool, CI only | a Backend-backed step gets a 5xx in CI only; the log names a missing program (`Browser was not found at the configured executablePath`) |
+| adb transport, mid-journey | `connection terminated: read failed` in the adb trace after boot, then lost `adb reverse`: usually guest RAM |
+| UiAutomator server | `RemoteDisconnected` while the adb transport stays up: the on-device server was relaunched |
+| Journey harness | a wait right after a navigation times out while the destination is on screen |
+| Journey harness, short screen | a wait for a label times out only on a short or landscape screen, which shows the content above it |
+| Product assertion | a screen or state mismatch with a screenshot |
+
+Then match the signal against [references/gotchas.md](references/gotchas.md). If nothing
+matches, [confirm the suspected cause](references/gotchas.md#confirm-a-suspected-cause)
+before changing code.
+
+Preserve the failure evidence. Do not blindly replay steps that send codes, verify sessions
+or charge payments just to get a passing screenshot. One passing run does not prove the
+build is reliable.
+
+## Feature work
+
+- Reuse the workspace's caches, venv and AVD configuration. Rerun a setup stage only when
+  the change touches what it proves (toolchain, dependencies, native code, harness).
+- Build the emulator ABI and run `scripts/device-run.sh` once per candidate HEAD.
+- After a failed journey, local or a CI dispatch, reproduce the failing checkpoint off CI
+  before you run it again: in the harness unit tests with the fake UI scripted to the
+  failing screen, or on the owned emulator. Show the fix passes there, then run the journey
+  once to confirm. Never send a guessed fix to CI to see whether it passes; a failure you
+  cannot reproduce earns one more run, with added diagnostics, then goes in the report as
+  unreproduced.
+- Report the source SHA, the journey command, its `PASS` markers or the failing stage,
+  and the cleanup exit. Nothing else: no APK hash, version inventory, screenshots, copied
+  logs or earlier attempts.
+- Integrated device acceptance (all ABIs, tablet, TalkBack, physical devices, a release
+  device campaign) runs at the release or campaign gate the spec or repo assigns it. Do
+  not recreate it per feature. Record it once, as pending, in its owning issue, never as
+  passed.
+
+## Evidence record
+
+For setup proof only. Record:
+
+- Source SHA, host OS and architecture, the Expo SDK, and the node, pnpm, JDK, Python and
+  emulator versions.
+- System image API, image type and ABI. The AVD name, serial and ports are run
+  identifiers, not shared resources.
+- Each stage's exit status and duration.
+- The APK's SHA-256 (`shasum -a 256` or `sha256sum`) and its per-ABI `lib/` entries
+  (`unzip -l`), checked on the APK itself rather than inferred from Gradle flags.
+- The journey's `PASS` markers and the cleanup results: database dropped, emulator exited,
+  container removed, no listeners left on the backend or Metro ports.
+- Earlier failed or incomplete attempts. A later pass does not erase them.
+
+State what the run does not prove: tablet, accessibility (TalkBack), physical devices,
+signing, distribution, and any feature acceptance beyond the journey. Publish only
+sanitized evidence: no authentication codes, session cookies, customer data or raw
+payment payloads.

package/skills/app-dev/android-foundation/assets/android-ci-job.yml

@@ -0,0 +1,217 @@
+# Android job for the repo's ci.yml. Merge these pieces into the existing workflow:
+#   1. the `android` filter into the `changes` job (and its output),
+#   2. the `android` job,
+#   3. the `android` lines into `gate`.
+# Replace every <placeholder>. See references/ci.md.
+
+jobs:
+  changes:
+    # ...existing changes job...
+    outputs:
+      android: ${{ steps.filter.outputs.android }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: filter
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        with:
+          filters: |
+            shared: &shared
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - '.github/workflows/ci.yml'
+            android:
+              - *shared
+              - '<android-workspace>/**'
+              - '<backend-paths-the-journey-drives>/**'
+              - '<device-harness-and-journey-scripts>'
+
+  android:
+    name: Android foundation (APK + device journey)
+    needs: changes
+    # Fork guard: fork code must never reach the self-hosted Android runners.
+    if: >-
+      needs.changes.outputs.android == 'true' &&
+      (github.event_name != 'pull_request' ||
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: [<self-hosted-android-runner-labels>]
+    timeout-minutes: 60
+    services:
+      postgres:
+        image: postgres:<major>
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: <ci-db-name>
+        ports: ['5432/tcp']
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s --health-timeout 5s --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '<node-major>'
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: '<pnpm-version>'
+          run_install: false
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Preflight Android runner
+        run: |
+          echo "runner=$RUNNER_NAME nproc=$(nproc)"
+          test -c /dev/kvm || { echo "runner has no /dev/kvm device" >&2; exit 1; }
+          test -r /dev/kvm
+          test -w /dev/kvm
+          node -e 'const fs = require("node:fs"); fs.accessSync("/dev/kvm", fs.constants.R_OK | fs.constants.W_OK)'
+          for component in platform-tools/adb platforms/android-<api> build-tools/<build-tools> \
+              ndk/<ndk> cmake/<cmake> emulator system-images/android-<emulator-api>/<target>/x86_64; do
+            test -e "$ANDROID_SDK_ROOT/$component" || { echo "runner image lacks $component" >&2; exit 1; }
+          done
+
+      - name: Allocate per-slot Android ports
+        run: |
+          if [[ "$RUNNER_NAME" =~ -([0-9]+)$ ]]; then slot=$((10#${BASH_REMATCH[1]})); else
+            echo "cannot derive a slot from $RUNNER_NAME" >&2; exit 2; fi
+          (( slot >= 1 && slot <= 15 )) || { echo "slot out of range: $slot" >&2; exit 2; }
+          emulator_port=$((5554 + 2 * slot))
+          {
+            echo "ANDROID_ADB_SERVER_PORT=$((5037 + slot))"
+            echo "ANDROID_EMULATOR_PORT=$emulator_port"
+            echo "ANDROID_EMULATOR_SERIAL=emulator-$emulator_port"
+            echo "ANDROID_BACKEND_PORT=$((<backend-base-port> + 10 * slot))"
+            echo "ANDROID_METRO_PORT=$((<metro-base-port> + 10 * slot))"
+          } | tee -a "$GITHUB_ENV"
+
+      # Optional: only on runners with a Gradle distribution mirror.
+      - name: Route the Gradle wrapper through the mirror
+        run: |
+          mirror="${GRADLE_DISTRIBUTIONS_MIRROR:?runner must set GRADLE_DISTRIBUTIONS_MIRROR}"
+          props=<android-project>/gradle/wrapper/gradle-wrapper.properties
+          node -e '
+            const fs = require("node:fs")
+            const [file, raw] = process.argv.slice(1)
+            const mirror = raw.replace(/\/?$/, "/")
+            const text = fs.readFileSync(file, "utf8")
+            const next = text.replace(
+              /^distributionUrl=https\\:\/\/services\.gradle\.org\/distributions\//m,
+              "distributionUrl=" + mirror.replace(/:/g, "\\:"),
+            )
+            if (next === text) throw new Error("distributionUrl was not rewritten")
+            fs.writeFileSync(file, next)
+          ' "$props" "$mirror"
+          grep '^distributionUrl=' "$props"
+
+      - name: Install dependencies
+        timeout-minutes: 12
+        run: pnpm install --frozen-lockfile
+
+      - name: Native tests and typecheck
+        run: |
+          pnpm --filter <android-workspace-package> test
+          pnpm --filter <android-workspace-package> typecheck
+
+      - name: Relax durability on the disposable Postgres
+        env:
+          PG_CONTAINER: ${{ job.services.postgres.id }}
+        run: |
+          docker exec "$PG_CONTAINER" psql -U postgres -v ON_ERROR_STOP=1 \
+            -c "ALTER SYSTEM SET synchronous_commit = off" -c "ALTER SYSTEM SET fsync = off" \
+            -c "SELECT pg_reload_conf()"
+
+      - name: Native auth against real PostgreSQL
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/<ci-db-name>
+        run: <native-auth-integration-test-command>
+
+      - name: Bundle Android JavaScript
+        env:
+          EXPO_PUBLIC_API_URL: https://app.invalid
+        run: pnpm --filter <android-workspace-package> exec expo export --platform android
+
+      - name: Build x86_64 debug APK
+        timeout-minutes: 30
+        env:
+          EXPO_PUBLIC_API_URL: https://app.invalid
+          ANDROID_USER_HOME: ${{ github.workspace }}/.cache/android-user
+        run: |
+          mkdir -p "$ANDROID_USER_HOME"
+          cpus="$(nproc)"
+          if [ -r /sys/fs/cgroup/cpu.max ]; then
+            read -r quota period < /sys/fs/cgroup/cpu.max
+            if [ "$quota" != max ]; then cpus=$(( (quota + period - 1) / period )); fi
+          fi
+          echo "gradle max-workers=$cpus (nproc=$(nproc))"
+          <android-project>/gradlew --project-dir <android-project> :app:assembleDebug --no-daemon \
+            -PreactNativeArchitectures=x86_64 --max-workers="$cpus"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Test device orchestration
+        run: <orchestration-unit-test-commands>
+
+      - name: Install UI automation
+        run: |
+          # Create the venv where the journey wrapper looks for it.
+          python3 -m venv <venv-dir-the-wrapper-reads>
+          <venv-dir-the-wrapper-reads>/bin/python3 -m pip install uiautomator2==<harness-pinned-version>
+
+      - name: Start the slot's ADB server
+        run: |
+          adb="$ANDROID_SDK_ROOT/platform-tools/adb"
+          "$adb" -P "$ANDROID_ADB_SERVER_PORT" start-server
+          "$adb" -P "$ANDROID_ADB_SERVER_PORT" version | head -1
+
+      - name: Device journey
+        uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0
+        env:
+          SHARD_ADMIN_URL: postgresql://postgres:postgres@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/postgres
+          SHARD_DB_NAME: <ci-db-name>
+        with:
+          api-level: <emulator-api>
+          arch: x86_64
+          target: <target>
+          disable-animations: true
+          enable-hw-keyboard: true
+          emulator-port: ${{ env.ANDROID_EMULATOR_PORT }}
+          cores: 4
+          # At 2 GB (the usual AVD value) the guest kernel's vsock allocations fail and adb drops
+          # mid-journey, taking every adb reverse with it (references/gotchas.md).
+          ram-size: 4096M
+          disable-linux-hw-accel: false
+          script: bash <path/to/foundation-journey-wrapper.sh>
+
+      # The sanitized capture (screenshots, UI dumps, backend and Metro logs; no auth codes,
+      # cookies or payment payloads), so a failure is diagnosed from the run, not the runner.
+      # <device-capture-dir> must be the directory the journey wrapper actually writes.
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: android-device-capture
+          path: <device-capture-dir>/
+          if-no-files-found: warn
+          retention-days: 7
+      - uses: actions/upload-artifact@v4
+        with:
+          name: android-debug-apk
+          path: <android-project>/app/build/outputs/apk/debug/*.apk
+          if-no-files-found: error
+          retention-days: 7
+
+  gate:
+    # ...existing gate job; add:
+    needs: [changes, android]   # plus the existing jobs
+    steps:
+      - env:
+          ANDROID: ${{ needs.changes.outputs.android }}
+          ANDROID_RESULT: ${{ needs.android.result }}
+        run: |
+          # inside the existing check script:
+          check android "$ANDROID_RESULT" "$ANDROID"

package/skills/app-dev/android-foundation/references/ci.md

@@ -0,0 +1,87 @@
+# Android CI
+
+Add an Android job to the repo's one `ci.yml`: build the debug APK and run the foundation
+journey on an emulator. Copy [assets/android-ci-job.yml](../assets/android-ci-job.yml) and
+fill every `<placeholder>`. Follow the `github-actions` skill for the `changes` job, the
+`gate` job, runner labels, pinning and hardening; this file covers only what is Android-
+specific.
+
+## Wire it in
+
+1. Add an `android` filter to the `changes` job: the app workspace, the native project,
+   the backend code the journey drives, the device harness and journey scripts, the
+   lockfile, and `ci.yml`. Leave docs out.
+2. Add the `android` job with `needs: changes` and
+   `if: needs.changes.outputs.android == 'true'` plus the fork guard: fork pull requests
+   never run on the self-hosted Android runners.
+3. Add `android` to `gate`'s `needs:` and a `check android "$ANDROID_RESULT" "$ANDROID"`
+   line. Require only `gate`.
+4. Before merging, open one Android-only PR and one docs-only PR. Confirm the job runs on
+   the first, is skipped on the second, and `gate` passes on both.
+
+## Runner
+
+- Run on a self-hosted Linux x64 runner class that has `/dev/kvm` mapped in and the SDK
+  preinstalled: platform-tools, the platform, build-tools, NDK, CMake, emulator and the
+  x86_64 system image the job boots. Never download SDK components in the job.
+- Preflight before any slow step: assert `/dev/kvm` is a character device, readable and
+  writable, and check it with Node's `fs.accessSync(R_OK | W_OK)`. The emulator action uses
+  that check; a host where `test -r/-w` passes but `accessSync` fails boots the emulator in
+  software for 10+ minutes. Assert each SDK component path exists.
+- Never let the emulator fall back to software: set `disable-linux-hw-accel: false`.
+- Derive per-slot ports from the runner's slot number when slots share a host network:
+  ADB server, emulator console (even port, 5554–5584), backend and Metro. Export them to
+  `$GITHUB_ENV` and start the ADB server on its own port.
+- Size Gradle from the cgroup CPU quota (`/sys/fs/cgroup/cpu.max`), not `nproc`. `nproc`
+  reports every host core and thrashes the native build.
+- Route the Gradle wrapper distribution and Maven repositories through the runner's
+  dependency proxy when it has one. Fail when the proxy variable is missing; never fall
+  back to direct downloads.
+
+## Build
+
+- Build `x86_64` only (`-PreactNativeArchitectures=x86_64`), with `--no-daemon`. Report
+  this APK as emulator evidence only. The all-ABI build stays a local or release step.
+- Bundle the JavaScript with `expo export --platform android` before the native build so
+  bundling errors fail fast.
+- Give the job `timeout-minutes: 60`, the install step its own short timeout, and the
+  APK build `timeout-minutes: 30`.
+
+## Database and journey
+
+- Run PostgreSQL as a job service on a random host port, with a health check. Turn off
+  `fsync` and `synchronous_commit` on it: the database is disposable.
+- Run the native auth/integration tests against that service before the device journey.
+- Unit-test the device orchestration scripts (journey wrapper, slot allocator, code
+  lookup) before booting the emulator.
+- Pin the UI automation package in a venv at the path the journey wrapper reads; use the
+  Python version the harness supports (3.12 on CI).
+- Boot the emulator with the SHA-pinned `reactivecircus/android-emulator-runner`, or the
+  runner's preinstalled emulator under an owned process group. Use the API level, target
+  and ABI of the preinstalled image, `disable-animations: true`, `ram-size: 4096M` (or
+  `-memory 4096` when launching the emulator directly), and the slot's console port. Run
+  the journey wrapper as its `script`. At 2 GB, the usual `avdmanager` value, adb drops
+  mid-journey
+  ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)).
+
+## Evidence
+
+- Upload the sanitized device capture (screenshots, UI dumps, backend and Metro logs) with
+  `if: always()` and a 7-day retention, from the directory the journey wrapper actually
+  writes. Sanitize before upload: no authentication codes, session cookies, customer data or
+  payment payloads. Diagnose a CI failure from this artifact; never require runner access.
+- Print enough to name the cause from the log alone: the message of the wait that timed
+  out (not only its exception class), the screen size and orientation, the labels on screen
+  and whether it scrolls, and the runner's free disk at preflight. A repo that uploads no
+  capture needs these in the log.
+- Upload the APK with `if-no-files-found: error`.
+- Treat one green run as one run. Fix flaky device failures at their cause instead of
+  rerunning, and do not change product code for them. An adb drop after boot means guest
+  RAM ([gotchas](gotchas.md#the-adb-transport-drops-mid-journey)). A `RemoteDisconnected`
+  with the adb transport still up means the uiautomator2 server was relaunched
+  ([gotchas](gotchas.md#remotedisconnected-right-after-a-new-process-connects)).
+
+## Traps
+
+Known CI symptoms and their fixes are in [gotchas.md](gotchas.md#ci-runners), along with
+the emulator and adb traps that also hit CI.