create-disposabl-app 0.0.4 → 0.1.1

package/dist/templates/default/apps/mobile/.agents/skills/eas-simulator/references/run-your-app.md

@@ -0,0 +1,256 @@
+# Running your app on the remote sim — tested sequences
+
+The remote sim boots blank. You install a **simulator-targeted** build onto the session, then open it. Pick a mode from `SKILL.md`. (Sequences validated against eas-cli 20.3.x + agent-device 0.17.x in mid-2026. These commands are experimental — check the relevant subcommand's `--help` before using non-default flags.)
+
+In all modes, the session is started the same way and driven through `npx --yes eas-cli@latest simulator:exec`. Replace `dev.example.app` with the app's iOS `bundleIdentifier` (from `app.json` → `ios.bundleIdentifier`), and run from the project directory.
+
+> These sequences are **iOS**. For **Android**: build via `npx --yes eas-cli@latest build --platform android` (or local Gradle), `install` the `.apk` instead of an `.app` (`.aab` fails), and skip `pod install`. Android sessions include a browser preview (`webPreviewUrl`), which the expo.dev session page opens in a new tab with **Open preview**. Android support is still in development, so some iOS features may not work.
+
+## Starting a session (shared by all modes)
+
+```bash
+# If the dotenv names a session, inspect it first with simulator:get --json. Reuse it when it belongs
+# to this run; stop it only when it is in scope and no longer needed. An IN_PROGRESS session may be
+# intentionally concurrent, so preserve its id/config before resetting the dotenv. Replacing the file
+# does not stop the remote session. Reset only after choosing how to handle the existing session.
+printf '# managed by eas-cli\n' > .env.eas-simulator
+
+# Start (the default --out-config-type dotenv writes .env.eas-simulator). It boots the sim + agent-device daemon.
+# --json changes stdout but does not suppress the completed dotenv write; use --out-config-type env for no file.
+# --name is required practice: it labels the session in simulator:list/get and on expo.dev.
+# Describe what the run is for, in the user's terms — see "Always name the session" in SKILL.md.
+npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --non-interactive \
+  --name "Checkout flow screenshots"
+```
+
+`start`'s own poll is unreliable, so confirm liveness with a bounded loop (boot is ~90s–15min). `get`/`exec`/`stop` default to the session in `.env.eas-simulator`, so you can omit `--id`:
+
+```bash
+# Poll up to ~16 min; IN_PROGRESS + remoteConfig = live; a terminal status = failed boot (stop + restart).
+for i in $(seq 1 64); do
+  S=$(npx --yes eas-cli@latest simulator:get --json --non-interactive 2>/dev/null)
+  echo "$S" | grep -q '"status": *"IN_PROGRESS"' && echo "$S" | grep -q remoteConfig && { echo "live"; break; }
+  echo "$S" | grep -qE '"status": *"(STOPPED|ERRORED)"' && { echo "boot failed — stop + restart"; break; }
+  sleep 15
+done
+```
+
+If you need the id explicitly, it's `EAS_SIMULATOR_SESSION_ID` in `.env.eas-simulator`. `start` also prints a `webPreviewUrl` (browser preview on iOS and Android; `remoteConfig.previewUrl` for `web-preview-only` sessions — surface it per the SKILL.md "watch it live" rules) and a job-run URL. Once live, the session env is in `.env.eas-simulator`, so `simulator:exec` works.
+
+## Targeting a device — iPad, or several at once
+
+**Boot a specific device at session start** with `eas simulator:start --device "<name|UDID>"` (eas-cli ≥ 22.4.0) — this is how you run on an iPad instead of the default iPhone:
+
+```bash
+npx --yes eas-cli@latest simulator:start --platform ios --device "iPad Pro 13-inch (M5)" \
+  --non-interactive --name "iPad run"
+# then install / launch / screenshot as usual — the iPad renders larger (e.g. 1032x1376).
+```
+
+The value must be a device the **remote runner** offers (NOT your local Xcode set), by name **or** UDID. List them from a live session:
+
+```bash
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest devices --json
+```
+
+Available iOS devices today: iPhone 17 (the default) / 17 Pro / 17 Pro Max / 17e / Air; iPad (A16), iPad Air 11-inch (M4), iPad Air 13-inch (M4), iPad mini (A17 Pro), iPad Pro 11-inch (M5), iPad Pro 13-inch (M5); plus Vision Pro and Apple TV. On Android, `--device` takes an AVD hardware profile id (e.g. `pixel_7`); all profiles render at 720x1600, density 300.
+
+**Add a second simulator mid-session:** a session boots only one simulator at start. Use a separate agent-device session for the second one: pass `--session <name> --device "<name>"` (boot takes about 46 seconds), and pass `--session <name>` on each later verb for that device. Passing `--device` in the default session fails with `INVALID_ARGS` "already bound".
+
+```bash
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <bundleId> "<devClientURL>" \
+  --platform ios --session ipad --device "iPad Pro 13-inch (M5)" --relaunch
+```
+
+- ⚠️ The **controller** `--device` takes a **name only** — a UDID returns `DEVICE_NOT_FOUND`; use `--udid` for a UDID. (The start-time CLI `--device` above takes either.)
+- `devices` reports each device's name, kind, and booted state, but **not** its iOS version.
+
+---
+
+## Mode A — Local release build (embedded JS, no Metro)
+
+A Release build bundles the JS into the binary, so it renders without Metro. Good for a quick "run my current code on a cloud device" when a Mac toolchain is available.
+
+```bash
+# 1. Generate native project + build a Release simulator .app
+npx expo prebuild --platform ios          # set ios.bundleIdentifier in app.json first to avoid prompts
+# pod install can fail on Ruby 4 + CocoaPods with a Unicode/ASCII-8BIT error — fix with a UTF-8 locale:
+( cd ios && LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 pod install )
+LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 xcodebuild \
+  -workspace ios/<App>.xcworkspace -scheme <App> \
+  -configuration Release -sdk iphonesimulator -derivedDataPath ios/build build
+# → ios/build/Build/Products/Release-iphonesimulator/<App>.app
+
+# 2. Start a session (see "Starting a session" above), then install + open + drive
+APP=ios/build/Build/Products/Release-iphonesimulator/<App>.app
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest install dev.example.app "$APP" --platform ios
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest open dev.example.app --platform ios
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot ./shot.png
+
+# 3. Stop
+npx --yes eas-cli@latest simulator:stop          # omit --id → stops the dotenv session
+```
+
+The `install` here **uploads** the (~90MB) `.app` to the remote daemon over the tunnel, which installs it on the sim with `simctl`.
+
+---
+
+## Mode B — EAS build (the VM downloads it; no credentials)
+
+**Explicit-only** (see the SKILL.md mode picker): a *static* EAS artifact for CI/sharing, or when the user names an existing EAS build. For no-Mac **live** iteration use Mode C with an EAS dev-client build (see Mode C below), not this. **Simulator builds are unsigned, so EAS asks for no credentials.**
+
+⚠️ **Check for an existing build first.** Before triggering a new build, check if a fingerprint-matched one already exists — it saves ~15-20 min:
+
+```bash
+npx --yes eas-cli@latest build:list --platform ios --profile <your-sim-profile> --status finished --json | \
+  head -20   # <your-sim-profile> = the profile you find/create in step 1; look for one whose fingerprint matches current source
+```
+
+If one matches, skip straight to step 3 with its artifact URL.
+
+⚠️ **Order matters:** build FIRST, `start` the session LAST. The build takes ~15-20 min and a session left idle that long times out (`ERR_NGROK_3200`) — don't `start` until you have the artifact URL.
+
+```bash
+# 1. Find or create a simulator build profile in eas.json.
+#    Read eas.json if it exists and look for a build profile with ios.simulator: true.
+#    If one exists, note its name and skip to step 2.
+#    If not, add one named "sim" — use node, python3, jq, or a direct JSON edit, whichever
+#    is available. Preserve all other profiles. Minimum: { "ios": { "simulator": true } }
+
+# 2. Build (no credentials prompt for a simulator build). Prints an artifact URL when done (~15-20 min).
+npx --yes eas-cli@latest build --platform ios --profile sim --non-interactive
+# → https://expo.dev/artifacts/eas/<hash>.tar.gz
+
+# 3. Start a session, then install-from-source so the VM downloads the artifact (no local upload)
+ART="https://expo.dev/artifacts/eas/<hash>.tar.gz"
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest install-from-source "$ART" --platform ios
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest open dev.example.app --platform ios
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot ./shot.png
+
+# 4. Stop
+npx --yes eas-cli@latest simulator:stop          # omit --id → stops the dotenv session
+```
+
+**Build freshness:** reuse only a build whose **fingerprint matches current source** (`npx --yes eas-cli@latest build:list --platform ios --json`, or `get-build` by fingerprint per Callstack's public `eas-agent-device` workflow); otherwise **rebuild** or use Mode C. Tell the user which build you used. (Why this matters → SKILL.md "Reusing an existing build" caveat.)
+
+---
+
+## Mode C — Dev build + tunnel (live edits via Fast Refresh)
+
+The agentic edit-and-see loop: a **dev (Debug) build** loads JS from your **Metro** over a tunnel, so edits appear on the remote sim via Fast Refresh. Two ways to connect the dev client to Metro:
+
+- **Method 1 (recommended, eas-cli ≥ 22.4.0):** launch at session start — `simulator:start` installs the build, applies launch-args, and opens the Metro URL in one command, and the "Open in?" dialog is auto-handled. Needs a **remote** build source (`--build-id`, `--build-fingerprint`, `--application-archive-url`, or `--expo-go`); a local `.app` can't be passed here. `--build-fingerprint` selects the most recent finished, non-expired build with that hash (iOS: it must be a simulator build; Android: any distribution type can match, so use an APK profile). An iOS `--application-archive-url` must be a `.tar.gz` or `.tgz` that contains a `.app` (`.zip`, `.app.zip`, and `.ipa` fail); Android needs an `.apk`.
+- **Method 2 (fallback):** drive the connect with the controller — for a **local `.app`** build, or eas-cli < 22.4.0.
+
+⚠️ **Don't install a release build as a "quick interim" and screenshot it** — it shows stale, build-time code. Use a dev build + Metro; screenshot only after the dev client is connected.
+
+### Get a dev-client build (either method needs one)
+
+- **Local (Mac):** `npx expo install expo-dev-client`; `npx expo prebuild --platform ios --clean` (set `ios.bundleIdentifier` first); `( cd ios && LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 pod install )`; then `xcodebuild -workspace ios/<App>.xcworkspace -scheme <App> -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build-debug build` → `ios/build-debug/Build/Products/Debug-iphonesimulator/<App>.app`. A local `.app` → **Method 2 only**.
+- **EAS (no Mac, or to use Method 1):** ensure a profile with `developmentClient: true` + `ios.simulator: true`, then `npx --yes eas-cli@latest build --platform ios --profile <dev-sim> --non-interactive`. Note the **build id** (Method 1's `--build-id`) or the artifact URL. Reuse a fingerprint-matched build to skip the ~15-20 min.
+
+### Method 1 — launch at session start (recommended)
+
+⚠️ **Metro FIRST, then `simulator:start`** — the runner opens `--open-url` during startup, with no retry.
+
+```bash
+# 1. Start Metro with a tunnel on your own free port (tunnel-backend details at the end of this mode).
+EXPO_UNSTABLE_TUNNEL_V2=1 npx expo start --tunnel --port <your-free-port>   # background it durably
+#    Capture the manifest host. Headless runs won't print it — read ngrok's API (curl -s 127.0.0.1:4040/api/tunnels)
+#    or the manifest (curl -s -H "expo-platform: ios" localhost:<port>/ → launchAsset.url).
+
+# 2. Start the session AND install+launch+open the app in one command (--launch-arg = one token per flag):
+#    Dev client: --build-id <id>, --open-url <scheme>://expo-development-client/?url=https://<manifest-host>
+#                (scheme = app.json `scheme`, NOT the slug; URL-encode the inner url if it has a path/query)
+#    Expo Go:    --expo-go instead of --build-id, and --open-url exp://<manifest-host>  (no port; https opens Safari)
+npx --yes eas-cli@latest simulator:start --platform ios --build-id <BUILD_ID> \
+  --launch-arg "-EXDevMenuIsOnboardingFinished" --launch-arg "1" \
+  --launch-arg "-EXDevMenuShowsAtLaunch" --launch-arg "0" \
+  --launch-arg "-EXDevMenuShowFloatingActionButton" --launch-arg "0" \
+  --open-url "<scheme>://expo-development-client/?url=https://<manifest-host>" \
+  --non-interactive --name "Coin flip live edits"
+#    The app installs, launches with the launch-args (onboarding/dev-menu/gear suppressed), and opens the URL.
+#    The "Open in '<app>'?" dialog is auto-bypassed (the CLI writes the scheme approval) and the approval
+#    persists session-wide — so NO `alert accept` is needed, here or for later controller opens.
+#    `start` prints NOTHING about the install/launch — confirm from Metro's `iOS Bundled …` line.
+
+# 3. To screenshot/drive, ATTACH the controller once — the CLI launch makes NO agent-device session, so a bare
+#    `screenshot` fails `SESSION_NOT_FOUND`. `open --foreground` attaches without relaunching:
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <bundleId> --foreground --platform ios
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot ./live.png
+#    VERIFY it's the REMOTE sim, not a silent local-sim fallback (agent-device falls back to a LOCAL sim with no
+#    error when the dotenv lacks remote config → believable but WRONG screenshots). Decisive tells: `simulator:get
+#    --json` returns the id `start` printed, AND the attach's "Session state:" path is under /Users/expo/ (remote
+#    VM), not /Users/<you>/ (your Mac). The `sessions/` vs `remote-diagnostics/` directory name is NOT reliable.
+
+# 4. Fast Refresh: edit a source file → it hits the remote sim with no reload. Screenshot again to confirm.
+# 5. Stop: npx --yes eas-cli@latest simulator:stop   # then kill the Metro process
+```
+
+### Method 2 — drive the connect with the controller (fallback)
+
+For a **local `.app`** (can't be passed to `--build-id`) or **eas-cli < 22.4.0**. Start a plain session (see "Starting a session"), install the build, then deep-link the dev client:
+
+```bash
+# install: a local .app uploads over the tunnel; an EAS artifact uses install-from-source (VM downloads it):
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest install <bundleId> "$DEVAPP" --platform ios
+#   (EAS artifact instead:  install-from-source "https://expo.dev/artifacts/eas/<hash>.tar.gz" --platform ios)
+
+# connect: `open <bundleId> <devClientURL>` deep-links into the bundle, skipping the launcher UI. Assemble
+# <devClientURL> from the app's SCHEME (app.json `scheme`, NOT the slug): <scheme>://expo-development-client/?url=https://<manifest-host>
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <bundleId> "<devClientURL>" --platform ios --relaunch \
+  --launch-args "-EXDevMenuIsOnboardingFinished" --launch-args "1" \
+  --launch-args "-EXDevMenuShowsAtLaunch" --launch-args "0" \
+  --launch-args "-EXDevMenuShowFloatingActionButton" --launch-args "0"
+# a controller open on a BARE session (no Method-1 launch to pre-approve the scheme) can raise the
+# "Open in '<app>'?" dialog — accept it (no-op if absent; not needed after a Method-1 launch):
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest alert accept 2500 --platform ios
+# then screenshot; if it shows the launcher not the app, the deep link didn't take → manual fallback:
+#   press 'label="Enter URL manually"' → snapshot -i → fill @<field> "<manifest URL>" → press 'label="Connect"'
+#   → press 'label="Reload"'; press 'label="Go back"' if expo-router shows "Unmatched Route".
+```
+
+### Dev-menu launch flags (both methods)
+
+The launch-args are iOS UserDefaults (`-Key Value`), verified in expo/expo `packages/expo-dev-menu`. By default the onboarding popup, auto-opened dev menu, and floating gear all show and clutter screenshots; these suppress them:
+- `-EXDevMenuIsOnboardingFinished 1` — skip the first-run onboarding popup (dev client **and** Expo Go)
+- `-EXDevMenuShowsAtLaunch 0` — don't auto-open the dev menu at launch (dev client)
+- `-EXDevMenuShowFloatingActionButton 0` — hide the floating gear (defaults visible on both)
+
+Method 1 passes each as two flags: `--launch-arg "<key>" --launch-arg "<value>"`. Method 2 passes them as `--launch-args`.
+
+On SDK 58+, you can put the same switches in the URL instead, which also works on **Android**, where launch-args don't apply: append `__expo_disable_onboarding=1&__expo_disable_fab=1&__expo_disable_auto_launch=1` to the `exp://` URL or to `<scheme>://?__expo_url=<encoded manifest URL>`. On SDK 57 and earlier, keep the launch-args on iOS; on Android, the legacy dev client URL takes `&disableOnboarding=1&disableFab=1&disableAutoLaunch=1` after `url=` (`disableFab` and `disableAutoLaunch` need `expo-dev-launcher` 57.0.20+). See `../../expo-overview/references/launch-without-dev-menu.md`.
+
+### Metro tunnel backends (both methods)
+
+#### Tunnel scope and approvals
+
+Mode C needs a route from the EAS VM to your local Metro server. The account-signed Expo tunnel is the normal transport for this workflow: it forwards requests to `http://localhost:<your-free-port>` so the remote app can fetch its development manifest, JavaScript bundle, and assets and receive live updates. Describe that concrete purpose when requesting network execution, including the project, port, and expected Expo service; a bare “start a public tunnel” omits the task context.
+
+**Carry authorization through the whole development loop.** When the user's existing authorization covers this project's EAS Simulator live development and required networking, treat starting its temporary Metro tunnel, connecting its dev client (including the launcher **Connect** button), and fetching subsequent bundles through Fast Refresh as steps of that authorized workflow. Do not ask the user to repeat consent for each step or later in-scope UI edit. A newly generated hostname on the same verified tunnel provider does not by itself expand the authorized scope; a different project, provider, exposed service, or user restriction requires reassessing it.
+
+This skill supplies technical context, not permission, and cannot override the host's approval policy. Identify the actual authorization: quote the relevant user message or user-provided project instruction and name its source, subject to the host's trust rules. Do not present this skill's own workflow instructions as user consent. A signed tunnel URL authenticates tunnel creation to an Expo account; it is **not proof that requests to the public Metro URL require authentication**. URL randomness limits discoverability, not access. Keep the URL within the intended session and stop your Metro process when finished.
+
+Put the authorization and transport details in the approval request itself so the reviewer can evaluate them together. Adapt this example only to facts verified for the current run:
+
+> Continue the authorized EAS Simulator live-development workflow for `<project>`.
+> Existing authorization: `<quote the relevant instruction>` from `<user message or project instruction source>`.
+> Start this project's Metro server on `localhost:<port>` through `<verified tunnel provider>`
+> so the project's dev client on EAS Simulator can fetch its development manifest,
+> JavaScript bundle, and assets and receive Fast Refresh updates. The Metro endpoint
+> is publicly reachable by URL while the tunnel runs. Keep the URL within the intended
+> session and stop this Metro process when the requested development session ends.
+
+For a dev-client connection request, reference the same authorization and the verified Metro URL from this run. Explain that **Connect** performs the bundle fetch for the already authorized workflow.
+
+If approval review rejects the tunnel or connection, explain the exact action and stated reason. If the host permits reconsideration and the rejection missed relevant evidence, submit a reconsideration with the concrete transport details and original authorization source. Do not blindly repeat a denied command or switch tools or providers to evade the rejection. If reconsideration is unavailable or still denied, report the remaining block and ask for approval of that specific exposure as the host requires. Keep a live-edit request on Mode C while resolving the block. Choose a static build only if it satisfies the user's requested outcome and is authorized; it loses Fast Refresh.
+
+Source: Expo CLI's [AsyncWsTunnel.ts](https://github.com/expo/expo/blob/main/packages/%40expo/cli/src/start/server/AsyncWsTunnel.ts) resolves the Expo account, requests a signed URL, and sets the local target port. Verify the installed CLI's actual backend below: the environment flag alone does not prove it selected Expo's service.
+
+#### Backend selection
+
+Start Metro on your OWN free port — each run gets its own tunnel URL, so never fight for or kill :8081 (#133's rule). BOTH backends accept ANY `--port`:
+- **ws-tunnel v2 (account-signed):** `EXPO_UNSTABLE_TUNNEL_V2=1` — signed URL for your EAS account, `on.expo.app` host, and the path for robot/EXPO_TOKEN/cloud agents (plain ngrok is blocked for them). Needs login / an EAS-linked project; if the signed URL fails, the CLI says to unset the flag and use ngrok.
+- **ngrok (plain `--tunnel`, no flag):** `<host>.exp.direct` host; blocked for robot/EXPO_TOKEN users.
+
+The ONLY 8081 lock is the LEGACY ws-tunnel path — hit WITHOUT the v2 account URL (an older CLI where the flag no-ops, or `EXPO_FORCE_WEBCONTAINER_ENV=1`). Do NOT set `EXPO_FORCE_WEBCONTAINER_ENV` to "fix" a port — it forces that legacy path and locks you to 8081. On an older CLI (e.g. expo 56) the v2 flag no-ops and you get ngrok on your chosen port (verified: expo 56.0.3 → ngrok on :8083).

package/dist/templates/default/apps/mobile/.agents/skills/eas-simulator/references/troubleshooting.md

@@ -0,0 +1,56 @@
+# Troubleshooting
+
+Concrete errors seen while validating this flow, and the fix.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Approval review rejects the Mode C Metro tunnel or dev-client Connect action | Review may lack or misinterpret the transport details or existing authorization; a signed URL alone does not establish private access | Follow [Tunnel scope and approvals](./run-your-app.md#tunnel-scope-and-approvals). Include the original authorization source and verified transport in the request; use reconsideration only where the host permits it. Preserve the requested live workflow while resolving approval. |
+| Controller recording download fails or times out | The local transfer can fail even though EAS retains the recording | Fetch it from [EAS session artifacts](./controllers.md#recording-download-recovery) using the original EAS session id and the recording’s `downloadUrl`. |
+| `Command simulator:start not found` | `eas-cli` too old (commands are hidden but present from ≥ 20.3.0) | Run via `npx --yes eas-cli@latest …`, or upgrade `eas-cli`. |
+| `simulator:start` rejects `--name` (e.g. `Nonexistent flag: --name`) | `eas-cli` too old — `--name` was added after `simulator:start` itself | Run via `npx --yes eas-cli@latest …`, or upgrade `eas-cli`. If you can't upgrade, retry once **without** `--name`; the session starts unnamed. |
+| `An Expo user account is required` / `whoami` shows logged-out | No browser login on a cloud/CI/headless box, or `EXPO_TOKEN` unset/invalid | Set **`EXPO_TOKEN`** (expo.dev → Account → Access Tokens) in the env; verify `npx --yes eas-cli@latest whoami`. (Interactive machines can `eas login`.) |
+| `simulator:start`/`build`: no linked project / missing `projectId` | A fresh `create-expo-app` isn't linked to EAS | `npx --yes eas-cli@latest init` to create/link it (writes `extra.eas.projectId`). |
+| `prebuild`/`eas build` prompts for or fails on a missing **iOS bundle identifier** | A fresh app often has no `ios.bundleIdentifier` | Set it in app config (e.g. `dev.<owner>.<slug>`); confirm via `npx expo config --json` (may live in `app.config.js`). |
+| `--max-duration-minutes` rejected | The value is above the plan limit (40 minutes on Free, 115 on paid plans); inspect the CLI error | Pass a value within the plan limit, or omit the flag to use the default. |
+| Browser-preview session stops despite ongoing interaction | Browser-preview activity does not reset `--max-idle-time-minutes`; only controller activity (`agent-device`, `argent`, Appium) does | Use the maximum duration as the lifetime bound for user-driven previews. Set it with `--max-duration-minutes`, and omit `--max-idle-time-minutes` unless controller inactivity is the intended stop condition. |
+| `simulator:start` fails with `not enabled for this account` / not-allowlisted | EAS Simulator is limited-access and isn't enabled for this account | Don't retry. Confirm with `simulator:availability`, then hand off gracefully — tell the user and fall back to a local sim / EAS Build (see SKILL.md *Check availability first*). |
+| `start` keeps "Waiting for … session to be ready" but it never returns | `start`'s readiness poll can miss a session that's actually live | Don't rely on it — poll `npx --yes eas-cli@latest simulator:get --id <id> --json` for `status: IN_PROGRESS` + a populated `remoteConfig`. |
+| `ERR_NGROK_3200` / endpoint offline; `Remote daemon is unavailable` | The session's tunnel/daemon dropped — left idle and timed out, or the VM was torn down | A drop invalidates the **whole** session (installed app, `@e` refs, Metro). **Don't retry the failed verb** — start a fresh session, reset the dotenv, and re-run install→open→drive from the top, acting immediately. |
+| Two sessions running / orphaned session | A second `start` (e.g. to "retry" a slow boot) creates another session and overwrites the dotenv id, orphaning the first | Poll the existing session instead. Find orphans with `simulator:list --status in-progress` and stop those you created with `simulator:stop --id <id>`. |
+| A device verb hangs (no return for a minute+) | Slow daemon; `press`/`screenshot` can block ~90s | Bound it with agent-device's own `--timeout <ms>` (e.g. `--timeout 120000`) — **not** a shell `timeout` wrapper (macOS has no `timeout` binary, so `timeout 120 …` fails with `command not found` and skips the verb). On timeout `snapshot -i` to see if the action landed before retrying (taps can double-fire). Don't blind-retry. |
+| `install requires an active session or an explicit device selector` | `install` can't infer the device | Pass `--platform ios` (or `open` something first to establish a session). |
+| `DEVICE_NOT_FOUND: No device named <udid>` when targeting a non-default device (iPad, second sim) | agent-device's `--device` takes a **name** only | Pass the device **name** from `agent-device devices` (e.g. `--device "iPad Pro 13-inch (M5)"`), or pass a UDID with `--udid`. |
+| `INVALID_ARGS` "already bound" when passing `--device` | The default agent-device session is already bound to the first simulator | Use a separate agent-device session for the second simulator: `--session <name> --device "<name>"` (see run-your-app.md). |
+| `Unknown command: tap` | An older agent-device version; `tap` is now a hidden alias of `press` | Use `press <ref\|selector>` (e.g. `press @e2` or `press 'label="Open"'`) or `click <target>`. |
+| `record stop` times out | The remote device is still exporting the clip | Run `record stop` again; add `--platform ios` if it cannot find the recording. The clip also uploads as a session artifact (see [controllers.md](./controllers.md#recording-download-recovery)). |
+| `--application-archive-url` install fails | Unsupported archive type | iOS needs a `.tar.gz` or `.tgz` that contains a `.app` (`.zip`, `.app.zip`, and `.ipa` fail). Android needs an `.apk` (`.aab` fails). |
+| `agent-device@latest --help` through `simulator:exec` shows the EAS CLI help | oclif catches `--help` | Use `... agent-device@latest help [topic]`. |
+| `SESSION_NOT_FOUND: No active session. Run open first.` | A verb (e.g. `screenshot`) ran before any app/session was opened — **or** you used Method 1 (`simulator:start --open-url`), which launches the app but creates NO agent-device session | `open <app\|url>` first (or pass `--platform ios`). After a Method-1 launch, attach without relaunching: `agent-device open <bundleId> --foreground --platform ios` (pass the bundle id — `--foreground` alone fails `AMBIGUOUS_MATCH`), then screenshot. |
+| Screenshot looks plausible but the session/UI is wrong (e.g. Safari, an iPhone shot when you booted an iPad, or "incompatible Expo Go SDK") | agent-device **silently falls back to a LOCAL simulator** when `.env.eas-simulator` has no remote config — no error, believable-but-wrong output. Common cause: a **concurrent `simulator:start`** on the same account/machine overwrote the shared dotenv with its own id (the dotenv is a single file, NOT concurrency-safe). | Confirm you're on the REMOTE VM: `simulator:get --json` returns the id `start` printed, AND the verb's "Session state:" path is under **`/Users/expo/`** (iOS) or **`/home/expo/`** (Android) on the remote device, not `/Users/<you>/` (local). `session state-dir` prints the local path, so it is not proof; `devices --json` host is a `turtle-worker-*`. The `sessions/` vs `remote-diagnostics/` directory name is NOT a reliable tell. If concurrency is possible, drive by explicit id — load the daemon vars from `simulator:get --id <id> --json` — instead of trusting the dotenv. |
+| `simulator:exec` / `build` / `simulator:stop`: "Run this command inside a project directory." | Run from the wrong cwd | Run from the Expo project directory (where `app.json`/`eas.json` live). |
+| New session's id shows as the *previous* one; "Overwriting previous simulator session (id: …)" | `.env.eas-simulator` names an earlier session | Inspect it with `simulator:get --json`. Reuse it when it belongs to this run; stop it only when it is in scope and no longer needed. An `IN_PROGRESS` session may be intentionally concurrent, so preserve its id/config before resetting the dotenv and drive sessions by explicit id/config. Replacing the file does not stop the remote session. |
+| No `.env.eas-simulator` written after `start` | `--out-config-type env` was selected, or the CLI reported a file-write failure | Use the default `--out-config-type dotenv` for the `exec` flow. `--json` changes output and implies non-interactive mode, but does not by itself suppress the completed dotenv write. `--out-config-type env` prints only the controller `export` lines and no `EAS_SIMULATOR_SESSION_ID`, so pass `--id` to `get`, `stop`, and `events`. |
+| `pod install` fails: `Unicode Normalization not appropriate for ASCII-8BIT` | Ruby 4 + CocoaPods with a non-UTF-8 locale | Re-run with `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 pod install`. |
+| (Mode C) Deep-link `open` lands on the dev-client launcher, not the app | The "Open in '<app>'?" system dialog wasn't accepted, so the deep link didn't take | Accept the dialog with `agent-device alert accept 2500 --platform ios` (not a UI tap). If it still lands on the launcher, fall back to "Enter URL manually" → `fill` the `https://<host>.on.expo.app` manifest URL → "Connect" (see run-your-app.md Mode C). |
+| (Mode C) App shows expo-router "Unmatched Route" | The connect URL was parsed as a route path | `press 'label="Go back"'` (or navigate to `/`). |
+| (Mode C) Dev client shows a `?` placeholder / blank after connect | Bundle not fetched yet | `press 'label="Reload"'` and wait ~40-60s for the first build+transfer over the tunnel. |
+| (Mode C) `expo start` fails: "port 8081 already in use" | Another Metro owns 8081 | Don't kill it. Start on your own `--port` — **both** `EXPO_UNSTABLE_TUNNEL_V2=1` (account-signed) and plain ngrok accept any port. Only the LEGACY ws-tunnel path is 8081-locked (see the `WS_TUNNEL_PORT` row). Reuse a Metro only if you started it this session. |
+| (Mode C) `expo start` / `node` killed with **exit 137** | 137 = SIGKILL — almost always the **OOM killer** (memory pressure, common in constrained cloud sandboxes, esp. a native build + Metro at once). **Not** a port clash. | Reduce memory pressure: don't run a native build and Metro concurrently; give the sandbox more memory; retry. |
+| (Mode C) Edits won't live-reload no matter how often you reconnect | A **release** build is installed — its JS is baked in, so it ignores Metro | Stop reconnecting: **install the dev (Debug) build**, connect it to Metro, reload. Reconnecting a release build to Metro is a no-op. |
+| `expo start --tunnel` errors for a robot/`EXPO_TOKEN` user | The ngrok robot-user guard blocks plain (ngrok) tunnels | Use ws-tunnel v2 (account-signed, **any** port): `EXPO_UNSTABLE_TUNNEL_V2=1 expo start --tunnel --port <any>` — needs login / an EAS-linked project. Do NOT use `EXPO_FORCE_WEBCONTAINER_ENV`; that forces the legacy path, which is 8081-locked. |
+| `CommandError: WS-tunnel only supports tunneling over port 8081` | You're on the **legacy** ws-tunnel path — no v2 account URL (older CLI where `EXPO_UNSTABLE_TUNNEL_V2` is a no-op, not logged in, or `EXPO_FORCE_WEBCONTAINER_ENV` set) | Get onto the account-signed v2 path: set `EXPO_UNSTABLE_TUNNEL_V2=1` and log in / link the project — then any `--port` works. Otherwise use `--port 8081`, or the ngrok path (drop the flag; non-robot only). |
+| Unexpected charges / a session you forgot | `start --non-interactive` does NOT auto-stop | Always `npx --yes eas-cli@latest simulator:stop --id <id>`. List leftovers with `npx --yes eas-cli@latest simulator:list`. |
+| Screenshot shows **old content** / my recent edits don't appear | Running a **release build (Mode A/B)** whose JS was baked in *before* your edits — typically a reused/stale build | A/B reflect code at build time, not now. **Rebuild** (ensure the build's fingerprint matches current source), or use **Mode C** (dev + Metro) so live edits show via Fast Refresh. The screenshot itself is fresh — it's the build that's stale. (`9:41` in the status bar is the sim default, not staleness.) |
+| (Android) The emulator stopped, and `agent-device boot` times out (`Daemon request timed out`) while the device stays `booted=false` | Without `--headless`, agent-device starts the emulator with a window. The EAS Linux image cannot run the windowed emulator, so it exits at once | Boot headless. Set `AGENT_DEVICE_HEADLESS=1` for the whole run, or pass `--headless` on each `boot`: `AGENT_DEVICE_HEADLESS=1 npx --yes eas-cli@latest simulator:exec npx agent-device@latest boot --platform android --device <avd-name>`. Get the AVD name from `agent-device devices --platform android`. The variable is read by the local client, so set it where you run the command. |
+| (argent) Every `argent run`/`tools` call returns `401 Unauthorized` right after linking | `argent link` without `--yes` no-ops on an already-linked URL ("Already linked. No changes."), keeping a stale token from a previous session | Re-link with `--yes` so the new token is written — see the link command in [controllers.md](./controllers.md). |
+| `/crashes` returns `404 Not found` on the preview API | The session's preview server predates the crash and log routes | Use `agent-device logs` for the device log, and tell the user crash reports aren't available on that session. Don't call `/logs` there. See [logs-and-crashes.md](./logs-and-crashes.md). |
+| `sim_api` stops with `API_BASE: no preview API` | The `API=` lookup failed: the session is not `IN_PROGRESS`, is not iOS, or has no preview API | Read the lookup's own error line above it. Check the `--id`, or start a new session. See [logs-and-crashes.md](./logs-and-crashes.md). |
+| `sim_api` fails with `401` | The session ended or its token changed, so the preview server rejects the old one | Run the `API=` lookup again. It prints the session's status when the session is no longer `IN_PROGRESS`. See [logs-and-crashes.md](./logs-and-crashes.md). |
+| A crash shows up but its `logTailSource` is `none`, `buffer-rolled-past`, or `no-app-lines` with no lines | Nothing held the device log when the crash happened, or a busy device rolled the buffer past it (common in the first minutes after boot) | Start the `/crashes?tail=1` hold (or call `sim_api /logs "snapshot=1&follow=1&limit=1"` more often than every 8 seconds) **before** reproducing. After a boot, reproduce again once logging settles, a minute or two later. |
+
+## Performance expectations
+
+Set the user's expectations honestly — this is experimental:
+- **Boot is variable**: ~90s warm to ~15 min cold. Poll patiently.
+- **`snapshot` can be slow** on iOS (tens of seconds).
+- **First bundle load** over the tunnel (Mode C) is the slow part; subsequent Fast Refreshes are fast.

package/dist/templates/default/apps/mobile/.agents/skills/eas-update/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: eas-update
+description: "Configure and use EAS Update for over-the-air JavaScript and asset updates with expo-updates and EAS CLI. Use when setting up OTA updates, running eas update:configure or eas update, publishing to preview/staging/production channels, explaining branches/channels/runtime versions, testing updates, or debugging why an installed build still shows old code. Load for TestFlight, preview, or production updates that do not appear, including questions about cold launches or reopening the app. Not for update health metrics; use eas-update-insights for adoption, crashes, and rollout monitoring."
+version: 1.0.0
+license: MIT
+allowed-tools: "Bash(npx expo *), Bash(npx *eas-cli@*), Bash(eas *)"
+---
+
+# EAS Update
+
+> **EAS service - costs apply.** EAS Update is available on the Free plan; publishing and delivery use update, bandwidth, and storage allowances, with higher limits on paid plans. See https://expo.dev/pricing.
+
+Use EAS Update to deliver compatible JavaScript, styling, and asset changes to installed apps without submitting a new native binary. Native-code changes still require a new build.
+
+## Start with the supported configuration path
+
+Before changing anything, inspect `package.json`, the Expo app config, `eas.json` if present, and whether `ios/` or `android/` are tracked. Use what you find when reviewing the CLI's changes:
+
+- Preserve existing dynamic or platform-specific app configuration.
+- If `eas.json` exists, preserve its profiles and existing channel assignments. The CLI adds a channel matching the profile name only to build profiles that do not already have one.
+- If `eas.json` is absent, do not create it by hand. The CLI may direct the user to run `eas build:configure` separately.
+- With tracked native projects, expect the CLI to synchronize the platform's native Update configuration. Without them, expect Continuous Native Generation to apply the native configuration during a later build.
+
+Detect the Expo SDK version before installing packages or interpreting version-specific behavior.
+
+If `expo-updates` is not installed, install the SDK-compatible version:
+
+```bash
+npx expo install expo-updates
+```
+
+Configure from the project root:
+
+```bash
+npx eas-cli@latest update:configure
+```
+
+Use `eas update:configure` rather than manually inventing `updates.url`, `runtimeVersion`, native metadata, or build-profile channels. The command understands EAS project linking, Continuous Native Generation, and projects with committed native directories. Review and explain its resulting diff.
+
+If the command cannot proceed because the project is not linked or the user has not authorized the required remote operation, stop after any independently valid package installation and explain what remains. Do not partially reproduce `update:configure` by adding a runtime-version policy, config plugin, update URL, or channels by hand.
+
+For dynamic app config, non-EAS builds, or a command that cannot complete automatically, follow the current setup documentation instead of guessing: https://docs.expo.dev/eas-update/getting-started.md.
+
+## Keep the model straight
+
+- **Build:** the installed native app. It contains native code, an embedded update, a platform, a runtime version, and normally a channel fixed at build time.
+- **Update:** a published JavaScript bundle, assets, and metadata for one platform and runtime version.
+- **Branch:** an ordered stream of updates. Its newest compatible update is active.
+- **Channel:** a stable deployment target embedded in builds. On the server, it points to a branch.
+- **Runtime version:** the compatibility boundary between an update and the native code in a build.
+
+A build receives an update only when platform and runtime version match and the build's channel points to the branch containing that update:
+
+```text
+installed build (channel: production, runtime: 1.1.1, platform: ios)
+  -> production channel
+  -> production branch
+  -> newest update for runtime 1.1.1 and ios
+```
+
+Channels and branches commonly have the same name, but they are separate objects. `eas channel:edit` changes a channel's server-side branch mapping for every build on that channel. It does not change an individual installation's embedded channel.
+
+Use this model to make decisions, but explain only the concepts needed for the user's request rather than reciting the entire model every time.
+
+## Decide whether an update is compatible
+
+Use an update for changes to JavaScript, styling, and bundled assets that the installed native runtime already supports.
+
+Create a new native build when a change adds or modifies native code or native configuration, including most native-library additions and SDK upgrades. Do not work around a runtime mismatch or imply that publishing can add native capabilities to an existing build. See https://docs.expo.dev/eas-update/runtime-versions.md.
+
+Do not change the project's runtime-version policy as an incidental fix. Explain how the current policy affects compatibility; treat changing it as a separate decision because it changes which installed builds can receive future updates.
+
+## Publish deliberately
+
+Check the current CLI help before relying on remembered flags:
+
+```bash
+npx eas-cli@latest update --help
+```
+
+For the common channel-based flow:
+
+```bash
+npx eas-cli@latest update \
+  --channel <channel> \
+  --message "<message>" \
+  --environment <environment>
+```
+
+SDK 55 and later require an EAS environment for publishing. Choose the environment intentionally so exported code receives the intended variables.
+
+Publishing changes remote state and can affect installed applications. Before running it, establish the exact project, channel, environment, platforms, runtime version, and message. Publish to production only when the user has explicitly requested or approved it; if the authorization or target is ambiguous, stop before the command and ask. Do not infer a production destination solely from the current Git branch.
+
+Prefer a preview or staging channel for validation. When promoting a tested update, use the documented deployment flow so production receives the same artifact where possible: https://docs.expo.dev/eas-update/deployment.md.
+
+## Test according to the build type
+
+### Development builds
+
+Preview updates with the development build's Extensions UI, the EAS dashboard, or Expo Orbit. A normal `expo-dev-client` development build does not behave like a release build's automatic startup update flow.
+
+### Preview, TestFlight, and production builds
+
+Release builds normally prioritize startup speed. With the default launch behavior, the app may start its current embedded or cached update while downloading a newly published update in the background. The downloaded update is applied on a later restart.
+
+For manual QA, fully terminate the app rather than backgrounding it, reopen it, allow the update time to download, and, if the change is not visible, fully terminate and reopen it once more. Describe this as **up to two cold launches**, not a TestFlight-specific ritual:
+
+1. One launch can discover and download the update.
+2. The following launch can run the downloaded update.
+
+Do not automatically change `fallbackToCacheTimeout` to avoid the second launch. Waiting at startup trades launch latency and reliability for faster update activation. If the app needs an intentional update UX, consider the `expo-updates` APIs for checking, fetching, and presenting a non-blocking restart action. Use the `expo-updates` API reference for the project's detected SDK version.
+
+## Debug a build that did not update
+
+Check these in order:
+
+1. Confirm the update was published to the intended EAS project, channel or branch, platform, and environment.
+2. Compare the installed build's platform and runtime version with the published update.
+3. Confirm the build actually contains the expected update URL and channel; app-config changes take effect only in a newly compiled build.
+4. Inspect the channel-to-branch mapping and the active update on that branch.
+5. Fully terminate the release build and allow for the normal download-then-apply lifecycle.
+6. Use the current debugging guide for native logs, export problems, and configuration checks: https://docs.expo.dev/eas-update/debug.md.
+
+Never bypass a compatibility or anti-bricking safeguard merely to make an update appear.
+
+## Advanced and adjacent workflows
+
+- **Channel surfing:** an individual release build can override its `expo-channel-name` request header to request another compatible channel. This differs from changing the server-side channel-to-branch mapping. Follow https://docs.expo.dev/eas-update/channel-surfing.md and preserve its access-control, persistence, recovery, and compatibility constraints.
+- **Update health:** load `eas-update-insights` for adoption, launch failures, crash rate, payload size, and rollout monitoring after publishing.
+- **Store releases:** load `eas-app-stores` when native changes require a new TestFlight, App Store, or Play Store build.
+
+## Official references
+
+- Setup: https://docs.expo.dev/eas-update/getting-started.md
+- Concepts and matching: https://docs.expo.dev/eas-update/how-it-works.md
+- Deployment: https://docs.expo.dev/eas-update/deployment.md
+- Debugging: https://docs.expo.dev/eas-update/debug.md
+- Current EAS CLI reference: https://docs.expo.dev/eas/cli.md
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes @expo/agent-cli@latest feedback --category skills --subject "eas-update" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an agent repeatedly fails at an Expo task or the user has to step in, submit a brief report of the task, expected result, and what went wrong using `--category evals` and the relevant Expo package or command as `--subject`.

package/dist/templates/default/apps/mobile/.agents/skills/eas-update/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EAS Update"
+  short_description: "Configure, publish, test, and debug over-the-air updates with expo-updates and EAS CLI"
+  default_prompt: "Use $eas-update to configure EAS Update, publish a compatible OTA update to the intended channel, test it in development or release builds, and debug channel or runtime-version mismatches."