From 00deda93177d89c7400284d3dfaa8bf61349e1b7 Mon Sep 17 00:00:00 2001
From: Jinwoo-H <jinwoo0825@gmail.com>
Date: Tue, 1 Sep 2026 16:39:46 -0400
Subject: [PATCH] docs(mobile): inventory every hosted WebView and native store
 entrypoint

mobile/README.md named three of the twelve hosted journeys and pointed at
package.json for the rest; the two native store suites appeared nowhere. Both
docs now carry the full list with the prerequisite that actually blocks each one
(simulator, adb device, release-signed install, Docker, POSIX signals), and say
which suites CI runs.

Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb
---
 .../mobile-hybrid-webview-architecture.md     | 10 +++--
 mobile/README.md                              | 43 +++++++++++++++----
 2 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/docs/reference/mobile-hybrid-webview-architecture.md b/docs/reference/mobile-hybrid-webview-architecture.md
index ca4fb5533a0..fc3efcea2df 100644
--- a/docs/reference/mobile-hybrid-webview-architecture.md
+++ b/docs/reference/mobile-hybrid-webview-architecture.md
@@ -248,9 +248,13 @@ pnpm test:e2e:hosted-mobile-webview:ssh:packaged
 ```
 
 The iOS hosted-WebView and packaged SSH journeys require macOS, Xcode, an
-available simulator, and Docker for the SSH topology. Android-specific commands
-are listed in `mobile/package.json`. Physical-device and store-signed evidence
-must be recorded separately from emulator results.
+available simulator, and Docker for the SSH topology. The nine
+`test:e2e:hosted-webview*` entrypoints under `mobile/`, and what each one needs,
+are tabulated in `mobile/README.md`. The native store suites live beside them:
+`pnpm --dir mobile test:native:ios-web-store` for Swift and
+`:orca-expo-mobile-web-shell:testDebugUnitTest` for Kotlin, both run by
+`.github/workflows/mobile-native-shell-tests.yml`. Physical-device and
+store-signed evidence must be recorded separately from emulator results.
 
 ## Support and Privacy
 
diff --git a/mobile/README.md b/mobile/README.md
index 6b80bd864cc..3ca1a8d43f6 100644
--- a/mobile/README.md
+++ b/mobile/README.md
@@ -209,17 +209,42 @@ pnpm lint:mobile-web
 pnpm build:mobile-web-rnw
 ```
 
-Hosted integration journeys:
+### Hosted WebView journeys
 
-```bash
-pnpm test:e2e:hosted-mobile-webview
-pnpm test:e2e:hosted-mobile-webview:ssh
-pnpm test:e2e:hosted-mobile-webview:ssh:packaged
-```
+Repository-root entrypoints build Desktop and the hosted bundle first, then hand
+off to the mobile runner:
 
-The iOS journeys require macOS, Xcode, and an available simulator. SSH journeys
-also require Docker. Android route, security, release, cache, and crash-loop
-commands are listed in `mobile/package.json`.
+| Command | Needs |
+| --- | --- |
+| `pnpm test:e2e:hosted-mobile-webview` | macOS, Xcode, a booted iOS simulator |
+| `pnpm test:e2e:hosted-mobile-webview:ssh` | the above, plus Docker for the SSH relay target |
+| `pnpm test:e2e:hosted-mobile-webview:ssh:packaged` | the above, against packaged mobile-web resources |
+
+Mobile-side entrypoints (`pnpm --dir mobile <script>`) drive an already-built
+Desktop through the `orca` CLI, so a paired Desktop must be reachable:
+
+| Command | Needs |
+| --- | --- |
+| `test:e2e:hosted-webview` | macOS, Xcode, a booted iOS simulator |
+| `test:e2e:hosted-webview:security` | same; runs only the origin/capability assertions |
+| `test:e2e:hosted-webview:android-routes` | an Android emulator or device on `adb`, with accessibility reads |
+| `test:e2e:hosted-webview:android-back` | an Android emulator or device on `adb` |
+| `test:e2e:hosted-webview:android-security` | an Android device on `adb` plus a local network probe port |
+| `test:e2e:hosted-webview:android-release` | a **user**-build (release-signed, non-debuggable) install; `--serial` or `ANDROID_SERIAL` |
+| `test:e2e:hosted-webview:android-crash-loop` | an Android device on `adb`; forwards the WebView DevTools socket |
+| `test:e2e:hosted-webview:android-corrupt-cache` | an Android device on `adb`, POSIX signals, and `--desktop-pid` |
+| `test:e2e:hosted-webview:ios-crash-loop` | macOS, Xcode, an iOS simulator reachable through `xcrun simctl` |
+
+### Native store suites
+
+| Command | Needs |
+| --- | --- |
+| `pnpm --dir mobile test:native:ios-web-store` | macOS with Xcode command line tools; compiles the shipped Swift store sources with `xcrun swiftc` and needs no simulator |
+| `cd mobile/android && ./gradlew :orca-expo-mobile-web-shell:testDebugUnitTest` | JDK 17 and the Android SDK, after `npx expo prebuild --platform android --no-install` |
+
+Both native suites run in CI from `.github/workflows/mobile-native-shell-tests.yml`.
+The hosted journeys do not: none of them can run on a GitHub-hosted runner that
+has an emulator and Docker at once.
 
 ## Protocol Compatibility