opencode-skills-collection 4.0.69 → 4.0.70

package/bundled-skills/eas-simulator/references/run-your-app.md

@@ -0,0 +1,240 @@
+# 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`, and skip `pod install`. Current simulator session types include a web preview, though Android support is still in development and may lack iOS parity.
+
+## 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` (iOS-only browser preview — 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 / 17 Pro / 17 Pro Max / 17e / Air, and iPad (A16), iPad Air 11"/13" (M4), iPad mini (A17 Pro), iPad Pro 11"/13" (M5).
+
+**Switch devices mid-session:** a session exposes ~16 sims but boots only one at start. Pass the **controller's** global `--device "<name>"` on `open` (and other verbs) to boot + target another; it stays booted alongside the first, so pass `--device` on each verb to say which it hits.
+
+```bash
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <bundleId> "<devClientURL>" \
+  --platform ios --device "iPad Pro 13-inch (M5)" --relaunch
+```
+
+- ⚠️ The **controller** `--device` resolves by **NAME only** — a udid returns `DEVICE_NOT_FOUND`. (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`, `--application-archive-url`, or `--expo-go`); a local `.app` can't be passed here.
+- **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/gabe/ (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`.
+
+### 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.
+
+Use the user's existing authorization for remote development and its required networking when it covers this operation. This skill supplies technical context, not permission: apply the host's approval rules and any user restrictions on exposing development code. A signed tunnel URL authenticates tunnel creation to an Expo account; it is **not proof that requests to the public Metro URL require authentication**. Keep the URL within the intended session and stop your Metro process when finished.
+
+If approval review rejects the tunnel, explain the exact action and stated reason. Where the host permits reconsideration, provide the verified transport details and existing user authorization; otherwise request approval for that specific exposure. 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. Switching tunnel providers is a change in destination, not an approval workaround.
+
+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/bundled-skills/eas-simulator/references/troubleshooting.md

@@ -0,0 +1,47 @@
+# Troubleshooting
+
+Concrete errors seen while validating this flow, and the fix.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Approval review rejects the Mode C Metro tunnel | Review needs the actual destination, development-code exposure, and user authorization; a signed URL alone does not establish private access | Follow [Tunnel scope and approvals](./run-your-app.md#tunnel-scope-and-approvals). Explain Expo's transport and 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 requested duration may not be supported by the account; inspect the CLI error | Use the default session limit when the custom duration is unavailable. |
+| Appium or browser-preview session stops despite ongoing interaction | Only activity reported through `agent-device` and `argent` resets `--max-idle-time-minutes`; Appium commands and browser-preview activity do not | Use the maximum duration as the lifetime bound for Appium and user-driven previews. Customize it with `--max-duration-minutes` when supported by the account, and omit `--max-idle-time-minutes` unless inactivity from a supported controller 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) | In a remote session agent-device's `--device` resolves by **name**, not udid (despite the CLI docs) | Pass the device **name** from `agent-device devices` (e.g. `--device "iPad Pro 13-inch (M5)"`), not the udid. |
+| `Unknown command: tap` | The tap verb is `press` | Use `press <ref\|selector>` (e.g. `press @e2` or `press 'label="Open"'`). |
+| `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/`** (remote), not `/Users/<you>/` (local); `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. |
+| `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.) |
+| (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). |
+
+## 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/bundled-skills/eas-workflows/SKILL.md

@@ -0,0 +1,119 @@
+---
+description: Curated upstream guidance for Eas Workflows; use when the workflow matches the user goal.
+name: eas-workflows
+allowed-tools: "Read,Write,Bash(node:*),Bash(npx *eas-cli@*) version: 1.0.0 license: MIT License"
+
+source_repo: expo/skills
+source_type: official
+source: expo
+date_added: '2026-09-21'
+risk: unknown
+---
+## When to Use
+- Use when this upstream workflow matches the user's stated goal.
+- Use when the task requires the procedures documented in this skill.
+
+# EAS Workflows Skill
+
+> **EAS service - costs apply.** EAS Workflows run on Expo Application Services, a paid product with free-tier limits. Each workflow job consumes your plan's build/compute minutes, and jobs that build or submit also need paid Apple Developer and Google Play accounts. Review https://expo.dev/pricing before triggering runs.
+
+Help developers write and edit EAS CI/CD workflow YAML files.
+
+## Reference Documentation
+
+Fetch these resources before generating or editing workflow files, or when answering syntax questions. First resolve this skill's directory, then use the fetch script in its `scripts/` directory. It is implemented using Node.js and caches responses using ETags for efficiency:
+
+```bash
+# Fetch resources
+node <skill-dir>/scripts/fetch.js <url>
+```
+
+1. **JSON Schema** — https://api.expo.dev/v2/workflows/schema
+   - It is NECESSARY to fetch this schema
+   - Source of truth for the workflow YAML structure; EAS CLI remains the authoritative final validator
+   - All job types and their required/optional parameters
+   - Trigger types and configurations
+   - Runner types, VM images, and all enums
+
+2. **Syntax Documentation** — https://raw.githubusercontent.com/expo/expo/refs/heads/main/docs/pages/eas/workflows/syntax.mdx
+   - Overview of workflow YAML syntax
+   - Examples and English explanations
+   - Expression syntax and contexts
+
+3. **Pre-packaged Jobs** — https://raw.githubusercontent.com/expo/expo/refs/heads/main/docs/pages/eas/workflows/pre-packaged-jobs.mdx
+   - Documentation for supported pre-packaged job types
+   - Job-specific parameters and outputs
+
+Do not rely on memorized values; these resources evolve as new features are added.
+
+## Workflow File Location
+
+Workflows live in `.eas/workflows/*.yml` (or `.yaml`). Each file must be 16 KiB or smaller.
+
+## Top-Level Structure
+
+A workflow file has these top-level keys:
+
+- `name` — Display name for the workflow
+- `on` — Triggers that start the workflow (at least one required)
+- `jobs` — Job definitions (required)
+- `defaults` — Shared defaults for all jobs
+- `concurrency` — Control parallel workflow runs
+
+Consult the schema for the full specification of each section.
+
+## Expressions
+
+Use `${{ }}` syntax for dynamic values. The schema defines available contexts:
+
+- `github.*` — GitHub repository and event information
+- `inputs.*` — Values from `workflow_dispatch` inputs
+- `needs.*` — Outputs and status from dependent jobs
+- `jobs.*` — Job outputs (alternative syntax)
+- `steps.*` — Step outputs within custom jobs
+- `workflow.*` — Workflow metadata
+
+## Generating Workflows
+
+When generating or editing workflows:
+
+1. Fetch the schema to get current job types, parameters, and allowed values
+2. Validate that required fields are present for each job type
+3. Verify job references in `needs` and `after` exist in the workflow
+4. Check that expressions reference valid contexts and outputs
+5. Ensure `if` conditions respect the schema's length constraints
+
+## Validation
+
+After generating or editing a workflow file, validate it with EAS CLI from the Expo project root:
+
+```sh
+npx -y eas-cli@latest workflow:validate .eas/workflows/<workflow.yml> --non-interactive
+```
+
+Run the command separately for each changed workflow file. It requires a logged-in EAS CLI session and a linked Expo project. Unlike schema-only validation, it also checks build profile references against the project's `eas.json` and performs EAS server-side validation. Fix every reported error and rerun the command until it prints `Workflow configuration YAML is valid.` Do not replace this command with a local YAML or JSON Schema validator.
+
+## Answering Questions
+
+When users ask about available options (job types, triggers, runner types, etc.), fetch the schema and derive the answer from it rather than relying on potentially outdated information.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "eas-workflows" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.
+
+
+## Examples
+
+```text
+User: Apply this skill to my current task.
+Assistant: Follow the workflow in this skill, cite limitations, and ask before risky steps.
+```
+
+## Limitations
+
+- Imported upstream skill; verify credentials, permissions, and safety boundaries before execution.
+- Does not replace environment-specific validation, testing, or maintainer review.

package/bundled-skills/eas-workflows/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EAS Workflows"
+  short_description: "Paid EAS service. Write and validate EAS workflow YAML files for Expo projects"
+  default_prompt: "Use $eas-workflows when creating or editing .eas/workflows YAML, validating EAS workflow configuration, or answering questions about workflow triggers, jobs, runners, and expressions."

package/bundled-skills/eas-workflows/scripts/fetch.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+const CACHE_DIRECTORY = resolve(import.meta.dirname, '.cache');
+const DEFAULT_TTL_SECONDS = 15 * 60; // 15 minutes
+
+export async function fetchCached(url) {
+  await mkdir(CACHE_DIRECTORY, { recursive: true });
+
+  const cacheFile = resolve(CACHE_DIRECTORY, hashUrl(url) + '.json');
+  const cached = await loadCacheEntry(cacheFile);
+  if (cached && cached.expires > Math.floor(Date.now() / 1000)) {
+    return cached.data;
+  }
+
+  // Make request, with conditional If-None-Match if we have an ETag.
+  // Cache-Control: max-age=0 overrides Node's default 'no-cache' to allow 304 responses.
+  const response = await fetch(url, {
+    headers: {
+      'Cache-Control': 'max-age=0',
+      ...(cached?.etag && { 'If-None-Match': cached.etag }),
+    },
+  });
+
+  if (response.status === 304 && cached) {
+    // Refresh expiration and return cached data
+    const entry = { ...cached, expires: getExpires(response.headers) };
+    await saveCacheEntry(cacheFile, entry);
+    return cached.data;
+  }
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  const etag = response.headers.get('etag');
+  const data = await response.text();
+  const expires = getExpires(response.headers);
+
+  await saveCacheEntry(cacheFile, { url, etag, expires, data });
+
+  return data;
+}
+
+function hashUrl(url) {
+  return createHash('sha256').update(url).digest('hex').slice(0, 16);
+}
+
+async function loadCacheEntry(cacheFile) {
+  try {
+    return JSON.parse(await readFile(cacheFile, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+async function saveCacheEntry(cacheFile, entry) {
+  await writeFile(cacheFile, JSON.stringify(entry, null, 2));
+}
+
+function getExpires(headers) {
+  const now = Math.floor(Date.now() / 1000);
+
+  // Prefer Cache-Control: max-age
+  const maxAgeSeconds = parseMaxAge(headers.get('cache-control'));
+  if (maxAgeSeconds != null) {
+    return now + maxAgeSeconds;
+  }
+
+  // Fall back to Expires header
+  const expires = headers.get('expires');
+  if (expires) {
+    const expiresTime = Date.parse(expires);
+    if (!Number.isNaN(expiresTime)) {
+      return Math.floor(expiresTime / 1000);
+    }
+  }
+
+  // Default TTL
+  return now + DEFAULT_TTL_SECONDS;
+}
+
+function parseMaxAge(cacheControl) {
+  if (!cacheControl) {
+    return null;
+  }
+  const match = cacheControl.match(/max-age=(\d+)/i);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+if (import.meta.main) {
+  const url = process.argv[2];
+
+  if (!url || url === '--help' || url === '-h') {
+    console.log(`Usage: fetch <url>
+
+Fetches a URL with HTTP caching (ETags + Cache-Control/Expires).
+Default TTL: ${DEFAULT_TTL_SECONDS / 60} minutes.
+Cache is stored in: ${CACHE_DIRECTORY}/`);
+    process.exit(url ? 0 : 1);
+  }
+
+  const data = await fetchCached(url);
+  console.log(data);
+}

package/bundled-skills/expo-animation/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.