@1aboveio/skills 1.0.12 → 1.0.14

package/skills/app-dev/android-development/references/framework-choice.md

@@ -0,0 +1,88 @@
+# Choose Kotlin/Compose or React Native
+
+Choose the smallest design that preserves the required behavior and reduces demonstrated
+coordination cost. Recommend a concrete default below; do not answer a framework decision
+with only "it depends." Apply the product's platform requirements and existing ADRs first.
+If one missing requirement would reverse the choice, name that requirement and ask for it.
+
+## Choose by situation
+
+| Situation | Recommendation | What must hold |
+| --- | --- | --- |
+| Existing React Native app; delay is repeated builds, cold setup or oversized verification | Keep React Native and repair the development loop. Do not propose migration for this evidence. | JS edits use the compatible running app; native edits use the verified incremental path; required acceptance stays intact. |
+| New flow with required Android/iOS UI reuse, mostly forms, lists and API interaction | Prefer React Native. Use platform-specific code only for demonstrated platform needs. | Verify the required native SDKs and platform behavior can be integrated without unacceptable ownership/synchronization costs. |
+| New Android-only flow dominated by hardware/SDK interaction, IME/Back/focus, windows or Activity lifecycle | Prefer Kotlin with Jetpack Compose as the starting design. Keep the related UI state and lifecycle under one coherent native owner. | Android-only scope is confirmed; backend/security contracts and required validation remain unchanged. Kotlin is not a promise of faster builds. |
+| Existing React Native flow repeatedly fails at demonstrated RN/native event or state coordination | First remove duplicated authority in the existing design. If that cannot meet the requirement, recommend an explicitly authorized Kotlin-owned coherent screen/flow as the next candidate, not many tiny bridged controls. | Define the boundary and its API, navigation and lifecycle responsibilities. Compare retained integration cost with the coordination being removed; preserve iOS obligations. |
+| Product-wide migration proposed, or platform/reuse/maintenance trade-offs remain unresolved | Keep the current stack for ordinary delivery. Present the candidate decision and obtain authorization for a bounded comparison or architecture change. | No migration, standalone host, benchmark campaign or new framework is implied by an ordinary bug fix. |
+
+Use the native-heavy recommendation for new design decisions, not as permission to rewrite
+working React Native code. A single native SDK is not by itself a reason to migrate a whole
+app. Conversely, shared UI is not a reason to force a platform-specific workflow through
+multiple owners when the required behavior cannot be supported reliably.
+
+## Compare the actual development paths
+
+| Dimension | React Native with native modules | Kotlin with Jetpack Compose |
+| --- | --- | --- |
+| UI styling and state iteration | Fast Refresh/reload can update supported JS/TS edits in an owned running debug app without a native build. | Compose Preview/Live Edit can help when the actual tooling supports them; structural changes still require compilation/deployment. |
+| Business logic | Focused JS/TS tests and runtime debugging; native contracts still need composition proof. | Focused Kotlin/JVM tests and runtime debugging; platform/backend contracts still need composition proof. |
+| Android APIs, hardware and SDKs | Native modules or components add a contract between JS and Android when needed. | Direct Android API/SDK integration can remove that cross-runtime adapter. |
+| IME, Back, focus and window lifecycle | Define ownership across the React tree, native component and Android host; asynchronous events must not create competing authority. | A coherent native screen can reduce inter-framework coordination, but still needs correct state, event and lifecycle handling. |
+| Build feedback | JS-only feedback can avoid Gradle; changed native inputs require native rebuilding. | Native changes use the supported incremental build/run path; Kotlin is not automatically a cheaper cold build. |
+| Tests | May combine JS, JVM, instrumentation and device journeys. | May combine JVM, instrumentation and device journeys; one UI toolkit does not eliminate integration or acceptance layers. |
+| Android/iOS reuse | Can share UI and logic, with explicit platform-specific behavior. | An Android Compose UI does not supply an iOS UI. Account for separate iOS work or an independently approved sharing strategy. |
+
+For an agent, compare tools it can actually operate. Do not count Android Studio Preview or
+Live Edit as available feedback in a headless CLI workflow without verifying access. Live
+Edit has edit/runtime constraints; preview or live updates do not prove native interaction,
+packaged startup or release behavior. Use the pinned toolchain, not assumed IDE capabilities.
+
+## Decide where ownership belongs
+
+For a native-heavy editor or sheet, assign one authoritative owner for draft state,
+Apply/Cancel, IME/Back handling and focus restoration. Define who accepts the final result
+and rejects stale events. Prefer a coherent screen/flow boundary over splitting each
+gesture and transition across runtimes. Keep business authorization and backend authority
+where the product contract requires them; moving UI ownership does not transfer those powers.
+
+Do not delete process-death recovery, persistence, identity, authorization, stale-callback
+guards or tests just because a bridge disappears. Identify which adapters become unnecessary
+and which correctness contracts remain. More Kotlin inside a React Native host may retain
+the boundary; it is not evidence for a pure-native architecture's cost.
+
+## Make and report the decision
+
+1. State the recommendation first: keep React Native, use React Native for the new flow,
+   prefer Kotlin/Compose for the new Android-only flow, or evaluate a specific native-owned
+   boundary. Name the platform and behavior facts that support it.
+2. Fix avoidable feedback-loop costs before comparing engineering effort: no repeated cold
+   setup, unnecessary test packaging or all-ABI build for every local edit. Keep the
+   [validation ladder](../SKILL.md#validation-ladder) and required CI in both paths.
+3. If a comparison is authorized, use the same representative behavior, backend/security
+   contracts and acceptance criteria. Compare total implementation/debug/verification effort,
+   failed iterations and their causes, plus build/startup cost using existing records.
+   Adapter lines are supporting evidence, not the decision metric. Do not invent timings,
+   a universal percentage threshold, or a new metrics service.
+4. A standalone native host can test whether an interaction becomes simpler, but excludes
+   production integration, navigation, deployment and iOS costs. Report that scope separately;
+   do not compare its narrow success with full production acceptance as equivalent work.
+5. Recommend adoption only for the scope supported by the evidence. Record platform/reuse
+   trade-offs, retained contracts, transition/rollback costs and unresolved proof in the
+   project's existing decision record. Ask for approval before changing an established stack
+   or launching a new experiment. Continue ordinary fixes within their authorized scope.
+
+## Avoids
+
+- Do not choose a framework from one slow build, a PR count or generic "excellent" ratings.
+- Do not promise that Kotlin removes Android lifecycle or backend correctness obligations.
+- Do not replace an optimized React Native baseline with an artificially cheap native demo.
+- Do not turn this guide into a Kotlin-only preference, mandatory experiment or migration gate.
+- Do not assume Android-only deployment or that cross-platform reuse has no product value.
+
+## Public tooling references
+
+Check behavior against the project's versions before selecting a feedback mechanism:
+
+- [React Native 0.81 build scope and ABI selection](https://reactnative.dev/docs/0.81/build-speed)
+- [Expo local development and Metro reuse](https://docs.expo.dev/guides/local-app-development/)
+- [Compose iterative development and Live Edit limitations](https://developer.android.com/develop/ui/compose/tooling/iterative-development)

package/skills/app-dev/{android-foundation → android-development}/references/gotchas.md

@@ -1,4 +1,36 @@
-# Android foundation gotchas
+# Android development gotchas
+
+## 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 |
+| Bridge passes, debug app fails to load | possible app/probe endpoint mismatch; inspect the actual request before choosing a cause ([React Native example](diagnosis.md#example-react-native-debug-app-uses-another-metro)) |
+| 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 [gotchas.md](gotchas.md). If nothing
+matches, [confirm the suspected cause](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.
 
 Known traps, each as signal, cause and fix. Match the signal before you dig. If none
 matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changing code.
@@ -58,10 +90,12 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
   recovers, Metro becomes unreachable, and a debug build loads assets from Metro. A
   backend reached at `10.0.2.2` does not use adb, so it keeps working. The usual trigger is
   an [adb transport drop](#the-adb-transport-drops-mid-journey); fix that first.
-- **Fix:** re-prove the bridge before every step whose screen is the first to load a Metro
-  asset: re-apply the reverse and check, from inside the device, that Metro answers. Doing
-  it only at app launch is not enough. Release builds embed their assets, so this is a
-  harness failure, not a product failure.
+- **Fix:** after a transport reconnect or observed mapping loss, restore the owned reverse
+  and verify device-to-Metro loading before continuing the affected check. Preserve a
+  harness's required checkpoints, but do not reset mappings or probe every screen by
+  default in an unchanged warm session. Determine the selected variant's real asset
+  mechanism before classifying the failure; an absent mapping alone does not prove
+  that the harness rather than the app caused the disconnect.
 
 ### The adb transport drops mid-journey
 
@@ -191,7 +225,10 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 
 - **Cause:** the slot's tool cache is empty, so the JDK or Python downloads from the
   internet.
-- **Fix:** seed the runner's `_tool/` directory from a sibling slot with the same image.
+- **Fix:** report the cold tool cache and hand provisioning to the runner owner through
+  `github-actions` and the fleet policy. A compatible cache seed may be their remedy;
+  do not copy or mutate either slot's shared `_tool/` state during an ordinary Android
+  diagnosis without a separate provisioning assignment.
 
 ### A Backend call fails only in CI: the runner lacks a tool the app launches
 

package/skills/app-dev/android-development/references/init.md

@@ -0,0 +1,104 @@
+# Project initialization
+
+`android-development` persists one section of project Android guidance. This helper is the
+deterministic writer behind that setup; `SKILL.md` owns the interactive choice that decides
+whether anything is persisted.
+
+## Usage
+
+```sh
+node {baseDir}/scripts/init.mjs [--repo-root <dir>] [--write]
+```
+
+- Preview is the default: it prints the planned action per file and writes nothing.
+- `--write` applies the plan. `--repo-root` selects the project; without it the nearest Git root
+  from the current directory is used, falling back to the current directory when there is none.
+- `--help` prints the usage line.
+- An unknown argument, an unresolvable root, a malformed marker or an unsafe target exits
+  non-zero with a message and no writes.
+
+## Files and ownership
+
+When Project or explicit init is selected, preview with the command above, then apply it
+with `--write` for the authorized missing additions. Existing conflicting policy needs a
+decision, not an overwrite. Verify the repo's actual commands and add only known bindings
+to a newly created Android section; report unresolved commands instead of guessing them.
+
+| File | Write |
+| --- | --- |
+| `CONTRIBUTING.md` | The `## Android development` section, wrapped in `<!-- conventions:android:start -->` / `<!-- conventions:android:end -->`, with `references/android-conventions.md` as its body. |
+| `AGENTS.md` | A short pointer to the selected `CONTRIBUTING.md`, added only when no correct loader link exists yet. |
+
+Each file is created only when it is absent. The helper never edits `CLAUDE.md`, never writes into
+a parent project, a home directory or global agent configuration, and never reaches outside the
+selected root.
+
+After applying authorized additions, verify that each existing supported agent entrypoint
+reaches the Android section, directly or through its instruction chain. The helper configures
+`AGENTS.md`; it does not certify an independent `CLAUDE.md` loader. Preserve existing chains
+and do not edit that entrypoint under this init permission. If one does not reach the guide,
+report the files configured and the unresolved loading path as partial setup. Obtain separate
+authorization for any additional loader edit instead of silently claiming complete setup.
+
+## Resolve the repo command map
+
+The initializer, not the deterministic writer, inspects existing scripts and guidance.
+Prefer the repo's working development route over adding another wrapper. For a new Android
+section, persist verified bindings in that section using this compact convention:
+
+| Lane | Working directory and command | Inputs/artifacts and owner | Verification status |
+| --- | --- | --- | --- |
+| L0 | Existing Metro start/reuse, focused tests and typecheck | JS delivery endpoint and owned running app | Observed or unresolved |
+| L1 | Incremental native build/install | Actual device ABI, scoped override, Gradle graph, app vs test APKs | Observed or unresolved |
+| L2 | Candidate startup/install and selected journey | Candidate artifact, supported selectors and disposable state owner | Observed or unresolved |
+| L3 | Existing required CI and release checks | Required test artifacts, device/ABI matrix and acceptance owner | Existing binding requirement |
+
+Inspect wrapper/task expansion using [feature work](feature-work.md#verify-command-expansion)
+when the owned toolchain permits it; reading a script is not executing its graph. Record
+what was inspected versus run and leave missing evidence unresolved. Initialization does
+not require a cold build, emulator provisioning, CI dispatch or acceptance campaign.
+Record native/JS invalidation triggers and [development-session ownership](workspace.md).
+Do not invent a command, selector or flag to complete the table.
+
+On later init runs, preserve the existing section and manual bindings without refreshing
+them. An authorized correction to stale commands is a deliberate policy edit, not a side
+effect of initialization or a new skill version.
+
+## Preservation
+
+Existing guidance wins over the template:
+
+- An existing `## Android development` heading, marked or hand-written, is left byte-for-byte,
+  including any repository-specific commands a caller added.
+- Every other section, hand edit and file is preserved; initialization appends and never
+  rewrites, reorders or refreshes.
+- Repeating the same initialization leaves configured files unchanged. There is no `--force` and
+  no update path: a new skill release never replaces saved project policy.
+- A valid symlink inside the project stays a link and its target is updated once. A dangling
+  link, a link resolving outside the selected root, a directory, unreadable or non-UTF-8 content,
+  and two targets resolving to one file are refused. Every target is validated before the first
+  write, so a refusal leaves the project untouched.
+- Refuse a mutation of a multiply hard-linked file or of an alias to the protected
+  `CLAUDE.md` entrypoint. This includes a shared AGENTS/CLAUDE target: preserve it and
+  report the boundary rather than silently granting a new write permission.
+- An existing pointer is reused only when its link resolves to the selected `CONTRIBUTING.md`,
+  and a new pointer is written relative to the real location of `AGENTS.md`. A link to some other
+  file, such as a nested package guide, does not count as this project's loader.
+
+## What it does not do
+
+Initialization is not installation or delivery. It does not install dependencies, SDK components
+or devices, provision an emulator, generate CI, open issues, push or release. It does not
+discover commands automatically: the initializer follows the command map above and reports
+what it could not resolve. Adding verified repository-specific bindings to the new section is
+part of that explicit initialization; a
+conflicting existing rule is reported rather than overwritten.
+
+## Scope and overrides
+
+The section applies to the project root it was written in, for later sessions. A Session choice
+keeps the ladder in conversation only and writes no files or configuration, including after
+compaction; an ordinary Android task reads existing guidance and does not initialize or ask about
+setup by itself. `SKILL.md` owns that interactive choice and its lifetime.
+
+Initialization does not authorize a commit, push, pull request, enqueue or release.

package/skills/app-dev/android-development/references/setup.md

@@ -0,0 +1,389 @@
+# Android setup and device execution
+
+Read [setup rules](#setup-rules) and [owned-resource cleanup](#owned-resource-cleanup)
+before these commands. All stages are for fresh setup proof; established workspaces use
+the [validation ladder](../SKILL.md#validation-ladder) and the
+[owned development session](#owned-development-session), and rerun only invalidated stages.
+
+Treat the shell blocks as an Expo/pnpm/UiAutomator example, not a required stack. Use the
+repo's verified package manager, native build, bundle/export step and existing test harness.
+Keep ownership, installed-toolchain, deadlines, cleanup and proof requirements mandatory;
+do not install Expo, Python automation or a new harness to make another RN project fit.
+
+Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
+functions or traps between calls: step 1 resolves the workspace and writes
+`.cache/android-env.sh`, which also `cd`s into it; every later block starts by sourcing it by
+absolute path, and steps 6–8 run as one command through the bundled `scripts/device-run.sh`.
+
+## Contents
+
+- [Fresh setup stages](#1-workspace-and-environment)
+- [Owned development session](#owned-development-session)
+- [Scoped ABI selection](#scoped-abi-selection)
+- [Setup rules](#setup-rules)
+- [Owned-resource cleanup](#owned-resource-cleanup)
+- [Setup evidence](#evidence-record)
+
+## 1. Workspace and environment
+
+Workspace precedence is owned by [workspace.md](workspace.md). Do not create a worktree,
+switch branch, fetch or reset when the caller supplied an isolated workspace.
+
+```bash
+set -euo pipefail
+ASSIGNED_WORKSPACE=<assigned-workspace-or-empty>
+CANDIDATE_HEAD=<candidate-head-or-empty>
+WORKSPACE="${ASSIGNED_WORKSPACE:?use the caller assignment or native-start result from workspace.md}"
+test -d "$WORKSPACE"
+git -C "$WORKSPACE" rev-parse --is-inside-work-tree >/dev/null
+cd "$WORKSPACE"
+actual_head="$(git rev-parse HEAD)"
+test -z "$CANDIDATE_HEAD" || test "$actual_head" = "$(git rev-parse "$CANDIDATE_HEAD^{commit}")" || {
+  echo "workspace HEAD $actual_head != candidate $CANDIDATE_HEAD; report it; do not switch" >&2
+  exit 1
+}
+mkdir -p .cache
+{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; printf 'export ANDROID_SOURCE_HEAD=%q\n' "$actual_head"; } > .cache/android-env.sh
+cat >> .cache/android-env.sh <<'ENV'
+
+# Repo-specific names, read from the repo's journey wrapper and device harness.
+export APP_FILTER=<android-workspace-package>         # pnpm --filter target
+export DEVICE_PYTHON_DIR=<venv-dir-the-wrapper-reads> # e.g. the default in the wrapper
+export DB_NAME_PREFIX=<db-prefix-the-harness-accepts> # the harness rejects other names
+export DB_URL_VAR=<harness-admin-url-variable>        # e.g. SHARD_ADMIN_URL
+export DB_NAME_VAR=<harness-db-name-variable>         # e.g. SHARD_DB_NAME
+
+# Host paths. Example values are for Apple Silicon with Android Studio.
+export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
+export ANDROID_HOME="$HOME/Library/Android/sdk"
+export ANDROID_SDK_ROOT="$ANDROID_HOME"
+export SOURCE_AVD="$HOME/.android/avd/<installed-avd>.avd"
+export SEED_GRADLE_HOME="$HOME/.gradle"
+export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
+
+# Private caches.
+export GRADLE_USER_HOME="$PWD/.cache/gradle"
+export ANDROID_USER_HOME="$PWD/.cache/android-user"
+export ANDROID_AVD_HOME="$PWD/.cache/android-avd"
+export TMPDIR="$PWD/.cache/tmp"
+export npm_config_cache="$PWD/.cache/npm"
+export npm_config_devdir="$PWD/.cache/node-gyp"
+export PNPM_CONFIG_STORE_DIR="$PWD/.cache/pnpm-store"
+export PNPM_CONFIG_CACHE_DIR="$PWD/.cache/pnpm"
+case "${JAVA_TOOL_OPTIONS:-}" in *java.io.tmpdir*) ;; *)
+  export JAVA_TOOL_OPTIONS="${JAVA_TOOL_OPTIONS:+$JAVA_TOOL_OPTIONS }-Djava.io.tmpdir=$TMPDIR" ;; esac
+
+# Run identifiers: an even console port in 5554-5584 (adb scans only that range),
+# and backend/Metro ports under the names the journey wrapper reads.
+export SETUP_AVD=<new-unique-avd-name>
+export EMULATOR_PORT=<even-port-5554-5584>
+export ANDROID_BACKEND_PORT=<free-port>
+export ANDROID_METRO_PORT=<free-port>
+# Choose the whole-journey deadline; zero disables it and is not suitable for unattended runs.
+export JOURNEY_SECONDS=<positive-journey-timeout-seconds>
+ENV
+source .cache/android-env.sh
+mkdir -p "$TMPDIR" "$npm_config_cache" "$npm_config_devdir" \
+  "$ANDROID_USER_HOME" "$ANDROID_AVD_HOME" .cache/logs
+
+node --version; pnpm --version; java -version; python3 --version
+adb version; "$ANDROID_HOME/emulator/emulator" -version
+# Versions come from the repo's native config and CI preflight.
+for component in platforms/android-<api> build-tools/<build-tools> ndk/<ndk> cmake/<cmake>; do
+  test -d "$ANDROID_HOME/$component" || { echo "Missing SDK: $component" >&2; exit 1; }
+done
+```
+
+The recorded standalone path is reused on retries; verify its lifecycle record names this
+run, branch and base. If an assigned path is missing, is not a Git worktree, or is at another
+revision, stop and report instead of creating another checkout. Never fall back to
+`../<repo>-android-setup`.
+
+If the wrapper reads ports or Python under other names, export aliases in
+`android-env.sh` **as well as** the bundled runner's required names. For example,
+`export APP_METRO_PORT="$ANDROID_METRO_PORT"`; both must select the same port. Adapt
+`DB_URL_VAR` and `DB_NAME_VAR` to the actual harness, not its fallback defaults.
+
+## 2. Install and check
+
+Run the repo's frozen install, relevant tests and typecheck. Export/bundle using the
+selected framework's supported command; use `expo export` only for an Expo project.
+Create a Python venv and pin UiAutomator only when the existing harness uses them.
+For Yarn/npm or an instrumentation-only harness, substitute its verified commands and
+omit unused pnpm/Python environment settings; do not invent replacements or install tools.
+
+```bash
+source <worktree>/.cache/android-env.sh
+pnpm install --frozen-lockfile --store-dir "$PWD/.cache/pnpm-store"
+pnpm --filter "$APP_FILTER" test
+pnpm --filter "$APP_FILTER" typecheck
+EXPO_PUBLIC_API_URL=https://app.invalid \
+  pnpm --filter "$APP_FILTER" exec expo export --platform android
+python3 -m venv "$DEVICE_PYTHON_DIR"
+"$DEVICE_PYTHON_DIR/bin/python3" -m pip install uiautomator2==<harness-pinned-version>
+```
+
+## 3. Gradle dependencies (pick one)
+
+Seed from a trusted Gradle home:
+
+```bash
+source <worktree>/.cache/android-env.sh
+mkdir -p "$GRADLE_USER_HOME/caches/modules-2/files-2.1"
+rsync -r --ignore-existing \
+  --exclude='*.lock' --exclude='*.lck' --exclude='*.tmp' \
+  "$SEED_GRADLE_HOME/caches/modules-2/files-2.1/" \
+  "$GRADLE_USER_HOME/caches/modules-2/files-2.1/"
+```
+
+Or wire a trusted Maven proxy into the private Gradle home. Append the exports to
+`android-env.sh` so the build in step 4 sees them. Route every repository the build uses,
+JitPack included; a route left unset goes straight upstream.
+
+If the opted-in proxy fails, stop and fix its routing; never fall back to direct
+downloads or disable TLS checks. The proxy covers Maven repositories only. Route the
+Gradle wrapper ZIP and pnpm as the repo's `CONTRIBUTING.md` requires. Without a seed or
+opted-in proxy, use upstream intentionally and allow for a cold build.
+
+```bash
+source <worktree>/.cache/android-env.sh
+cat >> "$PWD/.cache/android-env.sh" <<'ENV'
+export GRADLE_MAVEN_REPOSITORY=<proxy>/maven/
+export GRADLE_GOOGLE_REPOSITORY=<proxy>/google-maven/
+export GRADLE_PLUGIN_REPOSITORY=<proxy>/gradle-plugins/
+export GRADLE_JITPACK_REPOSITORY=<proxy>/jitpack/
+ENV
+curl --fail --silent --show-error --max-time 10 <proxy-health-url>
+install -d "$GRADLE_USER_HOME/init.d"
+install -m 0644 <path/to/proxy.init.gradle> "$GRADLE_USER_HOME/init.d/proxy.init.gradle"
+```
+
+## 4. Build
+
+```bash
+source <worktree>/.cache/android-env.sh
+pnpm build:android --max-workers=2 -Dorg.gradle.parallel=false \
+  -Pandroid.builder.sdkDownload=false --console=plain --info \
+  2>&1 | tee .cache/logs/gradle.log
+APK=<path/to/app/build/outputs/apk/debug/app-debug.apk>
+shasum -a 256 "$APK"            # sha256sum on Linux
+unzip -l "$APK" | grep -E 'lib/[^/]+/libreactnative\.so'
+```
+
+## 5. Owned emulator
+
+Copy only `config.ini`, never user data or snapshots. Verify that `image.sysdir.1` is an
+installed, host-compatible system image and that `target` matches it. Give the guest
+4 GB to avoid mid-journey ADB drops. A hand-written config needs the hardware keys in
+[gotchas](gotchas.md#a-hand-written-avd-misses-the-screen).
+
+```bash
+source <worktree>/.cache/android-env.sh
+test -f "$SOURCE_AVD/config.ini"
+test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
+test ! -e "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
+grep '^image.sysdir.1' "$SOURCE_AVD/config.ini"   # must be an installed, host-compatible image
+mkdir "$ANDROID_AVD_HOME/$SETUP_AVD.avd"
+# Copy without the source's RAM size and give the guest 4 GB (gotchas: adb transport drops).
+grep -Ev '^hw\.ramSize[[:space:]]*=' "$SOURCE_AVD/config.ini" > "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
+echo 'hw.ramSize=4096' >> "$ANDROID_AVD_HOME/$SETUP_AVD.avd/config.ini"
+printf 'avd.ini.encoding=UTF-8\npath=%s\ntarget=android-<api>\n' \
+  "$ANDROID_AVD_HOME/$SETUP_AVD.avd" > "$ANDROID_AVD_HOME/$SETUP_AVD.ini"
+```
+
+## 6–8. Cleanup, resources and journey: one command
+
+```bash
+source <worktree>/.cache/android-env.sh
+bash <skill-base-dir>/scripts/device-run.sh \
+  --drop node <path/to/device-harness.mjs> drop \
+  -- bash <path/to/foundation-journey-wrapper.sh>
+```
+
+Pass each command as separate words, not as one quoted string. The script:
+
+1. Registers the cleanup trap before anything starts.
+2. Refuses an emulator port outside 5554–5584 and any busy port.
+3. Starts the ADB server, then the emulator (its PID recorded), then `postgres` with
+   `--cidfile` on a random loopback port. Override the image with `POSTGRES_IMAGE`.
+4. Waits for `sys.boot_completed=1` and `pg_isready`. Startup/readiness and cleanup
+   commands have a 30-second limit (`BOUNDED_SECONDS`); exit 124 is terminal. The journey
+   uses the separate `JOURNEY_SECONDS` deadline. Leave time for cleanup after that deadline.
+5. Exports `$DB_URL_VAR`, `$DB_NAME_VAR` (`$DB_NAME_PREFIX` plus a unique suffix) and
+   `ANDROID_EMULATOR_SERIAL`, then runs the journey.
+6. Drops the database, stops the emulator PID (`TERM`, then `KILL` after 10 seconds),
+   removes the container by its CID, and prints `original_stage_exit=<n> cleanup_exit=<n>`.
+   It exits with the journey's status if the journey failed, else the cleanup status.
+
+The runner supervises the journey's process group. Journey children must stay in that
+group; a wrapper that deliberately creates detached services must stop those services
+through its own owner. Send TERM to the launcher and allow its cleanup to finish rather
+than killing it immediately. The generic runner inherits the caller's ADB endpoint and
+does not stop that server: use a verified private endpoint on a shared host and close it
+through the caller's owner. Capture the command's exit status and final summary line.
+
+Expect every selected scenario's `PASS` marker, screenshots, and backend and Metro logs
+when the selected variant uses those services. Preserve the failed checkpoint's evidence
+before cleanup. A release build with embedded assets does not require Metro by default.
+
+## Owned development session
+
+Apply the safety/proof requirements above to a new environment or invalidated setup
+assumptions, using only the repo's applicable stages and verified tools. The example
+commands are not universal requirements or a per-incremental-build checklist. Ordinary iteration runs against the
+owned development session described in [workspace.md](workspace.md): one development emulator
+and ADB endpoint, Metro, one compatible Gradle daemon on the private `GRADLE_USER_HOME`, and
+the workspace's build outputs. Rerun only the stages whose inputs changed, and end the session
+or hand it off before finishing.
+
+Keep that fast path fast:
+
+- Reuse the compatible Gradle daemon and private outputs where repo policy permits. CI or
+  one-shot verification may require `--no-daemon`; do not copy it automatically into a
+  local fast path, change global daemon settings or use shared writable caches. Preserve
+  the actual host/slot capacity limits and repo JVM constraints in every lane.
+- Add no configuration-cache, parallel, worker or JVM tuning without a measured need. Keep
+  the repo's JVM and resource-capacity settings, and keep this recipe's own flags as written.
+- A tracked native project that already builds and installs needs no routine `expo prebuild`
+  or `clean`, and no dependency reinstall.
+- Do not rerun the disposable stack from stages 5–8 for an edit. Reuse the existing
+  development owner. At L2/L3, follow the gate's fresh-state requirements; an authorized
+  fresh install on an existing owned emulator need not boot another guest if data isolation
+  is sufficient. The generic runner is not a second owner for an existing session.
+- Verify every Gradle task name against the actual task graph before using it. `assembleDebug`
+  and `installDebug` may also package instrumentation or test APKs, so do not treat either as
+  app-only proof without checking the packaged artifacts.
+
+### Scoped ABI selection
+
+Focused L1 work may build only the ABI of the owned device, where repo policy permits. Ask
+the device instead of guessing, and name its serial so both commands respect the caller's ADB
+endpoint. Give the probe a 30-second command deadline through the existing owner; do not
+wait indefinitely on a lost transport:
+
+```bash
+source <worktree>/.cache/android-env.sh
+adb -s <owned-serial> shell getprop ro.product.cpu.abi | tr -d '\r'
+# The ABIs the native build configures, e.g. the reactNativeArchitectures values.
+grep -n 'reactNativeArchitectures' <native-gradle-properties-file>
+```
+
+The printed ABI must appear in that configured list; stop and report any other value. Then
+scope one command to it, through the same build entry point as step 4, which forwards Gradle
+arguments. Tool shells do not keep variables between calls, so restate the verified value:
+
+```bash
+source <worktree>/.cache/android-env.sh
+DEVICE_ABI=<verified-abi-from-the-previous-command>
+pnpm <repo-build-entry> -PreactNativeArchitectures="$DEVICE_ABI" \
+  -Pandroid.builder.sdkDownload=false
+```
+
+Verify that this entry point forwards both properties, and retain the repo's applicable
+capacity and build-safety flags. Flags from an earlier command are not inherited.
+
+Do not change the shared checked-in ABI defaults, persist the flag in `gradle.properties`, or
+hardcode `x86` or `x86_64`, and keep the every-configured-ABI build as setup proof and release
+acceptance. An emulator-ABI build proves only that ABI.
+
+## Setup rules
+
+- Resolve the workspace first; [workspace.md](workspace.md) owns
+  precedence: an assigned isolated workspace and candidate HEAD win, feature work, fixes and
+  diagnosis reuse the owned workspace, and standalone setup creates one managed workspace
+  only with no usable assignment. Read its actual HEAD; never substitute `origin/main`, a new
+  branch or another checkout, mutate a peer's checkout or symlink its writable `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. Use the
+  repo's existing owned-resource launcher. For a new local setup without one, use
+  `scripts/device-run.sh` for stages 6–8 in one command. Do not wrap an existing owner
+  with a second emulator/database lifecycle.
+- Keep local writable caches private under `.cache/`: Gradle home, Android user/AVD
+  homes, temporary files, npm, node-gyp and pnpm. In CI, an already isolated runner slot
+  may provide those paths; verify its ownership contract rather than layering another
+  cache system on top. Never share writable state across concurrent owners.
+- 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 emulator-only
+  APK proves only that ABI. L1 focused native validation may use the emulator ABI where
+  repo policy permits, discovered from the owned device as in
+  [scoped ABI selection](#scoped-abi-selection); retain additional checks for affected ABI
+  configuration and all required native/ABI CI gates. Do not claim all-ABI proof from one
+  incremental build.
+- Determine how the selected build loads code and assets. A typical debug build needs
+  Metro; a release build normally embeds its bundle. Do not introduce Metro or debug
+  preferences into a release failure without evidence that the build uses them.
+  A successful build does not prove execution on a device.
+
+Ordinary edits reuse the [owned development session](#owned-development-session) instead of
+repeating these stages. Every stop still follows the cleanup rules below.
+
+## 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; these are short-lived, unlike the development workspace
+  and its private caches. 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.
+- The development runtime ends with the session, not after each check. Use its existing
+  owner's bounded shutdown, distinguishing supervised children/process groups from
+  persistent daemons. Shell `wait` and child exit codes apply only to children of that
+  shell; do not use them to attest termination of an adopted service or Gradle daemon.
+  The build client's exit does not mean its daemon exited. Record the daemon's own
+  identity and private Gradle home/version, not merely the client PID.
+- For a supervised runtime, stop through its harness owner and verify the owned group
+  and descendants exited; a Metro wrapper exiting alone is insufficient. For Gradle or
+  another daemon, use the verified owner-specific stop with the recorded private home,
+  version and endpoint, then verify the original process identity is gone and owned
+  endpoints are released where applicable. Never use a shared/global daemon stop,
+  `adb kill-server` or a broad kill. If scope or exit cannot be verified, report the
+  retained resource and cleanup gap or arrange explicit handoff; do not signal a guessed
+  PID or report success. Preserve the bounded-stop and failure-reporting rules below.
+- Never use broad `pkill`, `docker system prune` or a shared `adb kill-server` for cleanup.
+  Use the live child's process owner, not an ADB serial that may be reused. A numeric
+  PID can also be reused after exit; it is not durable ownership evidence.
+- 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 SIGKILL or a host crash, verify recorded resources before recovery: process
+  start identity, command/run scope and boot identity where available, or container ID
+  and ownership labels. Never signal a numeric PID solely because an old record names
+  it. If ownership cannot be verified, leave it alone and report the gap. Keep logs.
+- For the local setup flow, point the database URL only at its disposable loopback
+  container. An existing isolated remote test flow must use its own disposable data and
+  ownership checks. Never use development, production or another worker's database for
+  fixture writes or cleanup. A public render-only smoke needs no database.
+- Record existing working changes before tools run. If Expo rewrites `android/tsconfig.json`
+  or deletes `android/expo-env.d.ts`, remove only unwanted changes attributable to that tool
+  execution. Preserve pre-existing and intentional task edits. If attribution is unclear,
+  retain the files and report the conflict; do not restore a whole file merely because
+  Expo touched it.
+
+## Evidence record
+
+For setup proof only. Record:
+
+- Source SHA and the workspace root/path/base/branch/owner from the lifecycle record; 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.