novahiz 0.1.0

package/bundled-skills/eas-simulator/references/troubleshooting.md

@@ -0,0 +1,44 @@
+# Troubleshooting
+
+Concrete errors seen while validating this flow, and the fix.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `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 flag is **paid-plan only** | Drop `--max-duration-minutes` to use the default. |
+| `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 / surprise double billing | A second `start` (e.g. to "retry" a slow boot) creates a second billed session and overwrites the dotenv id, orphaning the first | Never `start` again to retry — poll the existing session instead. Find orphans with `simulator:list --status in-progress` and stop each 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: …)" | The stale `.env.eas-simulator` had an old `EAS_SIMULATOR_SESSION_ID`; the warning line masks the new id | Reset the dotenv before `start`: `printf '# managed by eas-cli\n' > .env.eas-simulator`. |
+| No `.env.eas-simulator` written after `start` | `--json` suppresses the dotenv | Run `start` *without* `--json` for the `exec` flow; with `--json` you must read `remoteConfig` from stdout and set the env yourself. |
+| `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-update/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: eas-update
+description: "EAS service (paid). 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 submit-expo-feedback@latest --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 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.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EAS Update"
+  short_description: "Paid EAS service. 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."

package/bundled-skills/eas-update-insights/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: eas-update-insights
+description: "EAS service (paid). Check the health of published EAS Update: crash rates, install/launch counts, unique users, payload size, and the split between embedded and OTA users per channel. Use when the user asks how an update is performing, whether a rollout is healthy, how many users are on the embedded build vs OTA, or wants to gate CI on update health."
+version: 1.0.0
+license: MIT
+allowed-tools: "Bash(eas *)"
+---
+
+# EAS Update Insights
+
+> **EAS service - costs apply.** Insights cover updates published through EAS Update, a paid Expo Application Services product with free-tier limits. Update delivery and the data behind these commands count against your plan's EAS Update usage. Review https://expo.dev/pricing.
+
+Query the health of published EAS Update directly from the CLI: launches, failed launches, crash rates, unique users, payload size, the embedded-vs-OTA user split per channel, and the most popular updates per runtime version. The data is the same data that powers the update and channel detail pages on expo.dev; these commands expose it in the terminal in human and JSON form.
+
+## When to use this skill
+
+Use this when the user wants to assess the health or adoption of a published EAS Update: crash rates, install counts, unique users, bundle size, or the split between embedded and OTA users on a channel.
+
+Example prompts:
+
+- "How is the latest update doing?"
+- "Is the latest update healthy?"
+- "Is the new release crashing more than the last one?"
+- "How many users are on the latest update vs the embedded build?"
+- "Which update is most popular on production right now?"
+- "How big is our update bundle?"
+
+Also fits: post-publish rollout monitoring and regression detection.
+
+Don't use when the user needs per-user crash detail or device-level reporting; this skill only exposes aggregate EAS metrics.
+
+## Prerequisites
+
+- `eas-cli` installed (`npm install -g eas-cli`).
+- Logged in: `eas login`.
+- For `channel:insights`: run from an Expo project directory (the command resolves the project ID from `app.json`). `update:insights` only needs a login.
+
+## Commands at a glance
+
+| Command | Purpose |
+|---|---|
+| `eas update:list` | Discover recent update groups, their `group` IDs, and branch names |
+| `eas update:insights <groupId>` | Per-platform launches, failed launches, crash rate, unique users, payload size, daily breakdown |
+| `eas update:view <groupId> --insights` | Update group details + the same metrics appended |
+| `eas channel:insights --channel <name> --runtime-version <version>` | Embedded/OTA user counts, most popular updates, cumulative metrics for a channel + runtime |
+
+All of these support `--json --non-interactive` for programmatic parsing.
+
+## Discovering IDs
+
+Before querying insights for an update group, you need its `group` ID. Use `eas update:list` with either `--branch <name>` (updates on that branch) or `--all` (updates across all branches). Always pass `--json --non-interactive` when running non-interactively; without a branch/`--all` flag the command will otherwise prompt for a branch selection:
+
+```bash
+# Latest group id across all branches
+eas update:list --all --json --non-interactive | jq -r '.currentPage[0].group'
+
+# Latest group id on a specific branch
+eas update:list --branch production --json --non-interactive | jq -r '.currentPage[0].group'
+```
+
+The JSON response has a `currentPage` array with one entry per update group (both platforms of the same publish are collapsed into one entry):
+
+```json
+{
+  "currentPage": [
+    {
+      "branch": "production",
+      "message": "\"Fix checkout crash\" (1 week ago by someone)",
+      "runtimeVersion": "1.0.6",
+      "group": "03d5dfcf-736c-475a-8730-af039c3f4d06",
+      "platforms": "android, ios",
+      "isRollBackToEmbedded": false
+    }
+  ]
+}
+```
+
+Entries also carry `codeSigningKey` and `rolloutPercentage`, but only when those features are in use for the group (undefined values are omitted from the JSON output).
+
+When called with `--branch <name>`, the response also includes `name` (the branch name) and `id` (the branch ID) at the top level.
+
+## `eas update:insights <groupId>`
+
+Shows launches, failed launches, crash rate, unique users, launch asset count, and average payload size for a single update group, broken down **per platform** (iOS, Android), plus a daily breakdown of launches and failures.
+
+### Basic use
+
+```bash
+eas update:insights 03d5dfcf-736c-475a-8730-af039c3f4d06
+```
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--days <N>` | Look back N days. Default: **7**. Mutually exclusive with `--start`/`--end`. |
+| `--start <iso-date>` / `--end <iso-date>` | Explicit time range, e.g. `--start 2026-04-01 --end 2026-04-15`. |
+| `--platform <ios\|android>` | Filter to a single platform. Omit to see all platforms in the group. |
+| `--json` | Machine-readable output. Implies `--non-interactive`. |
+| `--non-interactive` | Required when scripting. |
+
+### JSON output shape
+
+Top level: `groupId`, `timespan` (`start`, `end`, `daysBack`), and `platforms[]` with one entry per platform the group was published to. Each platform entry has `updateId`, `totals` (`uniqueUsers`, `installs`, `failedInstalls`, `crashRatePercent`), `payload` (`launchAssetCount`, `averageUpdatePayloadBytes`), and a `daily[]` time series of `{ date, installs, failedInstalls }`.
+
+For the complete schema and field reference, see [references/update-insights-schema.md](./references/update-insights-schema.md).
+
+Fields that matter for health assessment:
+
+- `platforms[].totals.crashRatePercent`, computed as `failedInstalls / (installs + failedInstalls) * 100`. Zero when there are no installs.
+- `platforms[].totals.installs` and `uniqueUsers` give the adoption signal.
+- `platforms[].daily` is a time series, useful for spotting a sudden spike in failures.
+
+### Errors
+
+- `Could not find any updates with group ID: "<id>"` — group doesn't exist or you lack access.
+- `Update group "<id>" has no ios update (available platforms: android)` — `--platform ios` was used but the group wasn't published for iOS.
+- `EAS Update insights is not supported by this version of eas-cli. Please upgrade ...` — the server deprecated a field the CLI relies on. Run `npm install -g eas-cli@latest`.
+
+## `eas update:view <groupId> --insights`
+
+Extends the standard `update:view` output with the same per-platform insights, inline.
+
+```bash
+# Human-readable
+eas update:view 03d5dfcf-... --insights
+eas update:view 03d5dfcf-... --insights --days 30
+
+# JSON: wrapped as { updates: [...], insights: {...} }
+eas update:view 03d5dfcf-... --json --insights
+```
+
+Without `--insights`, `update:view` behaves exactly as before — no JSON shape change for existing consumers. The `--days` / `--start` / `--end` flags only apply when `--insights` is set; passing them alone errors.
+
+## `eas channel:insights --channel <name> --runtime-version <version>`
+
+Shows, per channel, how many users are on the embedded build vs over-the-air updates and which updates are pulling the most traffic. Must be run from an Expo project directory.
+
+### Basic use
+
+```bash
+eas channel:insights --channel production --runtime-version 1.0.6
+```
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--channel <name>` | **Required.** The channel name (e.g. `production`, `staging`). |
+| `--runtime-version <version>` | **Required.** Match exactly what was published. Check `runtimeVersion` values in `update:list`. |
+| `--days <N>` | Look back N days. Default: **7**. |
+| `--start` / `--end` | Explicit time range, like `update:insights`. |
+| `--json` / `--non-interactive` | Machine-readable output. |
+
+### JSON output shape
+
+Top level: `channel`, `runtimeVersion`, `timespan`, `embeddedUpdateTotalUniqueUsers`, `otaTotalUniqueUsers`, `mostPopularUpdates[]` (each with `rank`, `groupId`, `message`, `platform`, `totalUniqueUsers`), `cumulativeMetricsAtLastTimestamp[]`, plus chart-shaped `uniqueUsersOverTime` and `cumulativeMetricsOverTime` objects with `labels` and `datasets`.
+
+For the complete schema and field reference, see [references/channel-insights-schema.md](./references/channel-insights-schema.md).
+
+Fields that matter:
+
+- `embeddedUpdateTotalUniqueUsers` is the count of users running the embedded (binary-bundled) build.
+- `mostPopularUpdates[]` is updates ranked by `totalUniqueUsers`. **Caveat**: this is the top-N the server returns; `otaTotalUniqueUsers` is a sum of that list and may undercount total OTA reach if more than top-N updates are active.
+- `uniqueUsersOverTime` and `cumulativeMetricsOverTime` are daily data series for charting.
+
+### Errors
+
+- `Could not find channel with the name <name>` — typo or wrong account.
+- "No update launches recorded" in the table / empty `mostPopularUpdates` in JSON — no OTA update has been launched for that channel + runtime yet. Usually means the channel is still serving the embedded build only.
+
+## Common workflows
+
+### Verify the update I just published is healthy
+
+```bash
+# 1. Grab the latest publish on production
+GROUP_ID=$(eas update:list --branch production --json --non-interactive \
+  | jq -r '.currentPage[0].group')
+
+# 2. Give it some adoption time (minutes to hours), then check crash rate
+eas update:insights "$GROUP_ID" --json --non-interactive \
+  | jq '.platforms[] | {platform, installs: .totals.installs, crashRate: .totals.crashRatePercent}'
+```
+
+Compare the `crashRate` across platforms and against previous releases; sudden spikes or asymmetric behaviour (iOS spiking while Android is flat, or vice versa) is the signal to investigate.
+
+### Compare adoption between two channels
+
+```bash
+for channel in production staging; do
+  echo "--- $channel ---"
+  eas channel:insights --channel "$channel" --runtime-version 1.0.6 --json --non-interactive \
+    | jq '{
+        channel,
+        embedded: .embeddedUpdateTotalUniqueUsers,
+        ota: .otaTotalUniqueUsers,
+        topUpdate: .mostPopularUpdates[0]
+      }'
+done
+```
+
+### Detect a rollout regression in the last 24 hours
+
+```bash
+eas update:insights "$GROUP_ID" --days 1 --json --non-interactive \
+  | jq '.platforms[] | select(.totals.crashRatePercent > 1)'
+```
+
+### Summarize group metrics for release notes
+
+```bash
+eas update:view "$GROUP_ID" --insights --days 30
+```
+
+Human-readable group details plus 30 days of launches/failures per platform — suitable for pasting into a changelog or incident review.
+
+## Output tips
+
+- Pipe JSON through `jq`; payloads are structured for easy filtering.
+- `--json` implies `--non-interactive`, but passing both is explicit and scripting-friendly.
+- Dates in `daily[].date` are UTC ISO timestamps; the human-readable table renders them as `YYYY-MM-DD` (UTC).
+- The CLI table labels say "Launches" / "Crashes" while JSON uses `installs` / `failedInstalls`. Same field, different display name.
+
+## Limitations
+
+- **Unique users across platforms** may double-count users who run the same publish on both iOS and Android. The same caveat applies to `otaTotalUniqueUsers` in channel insights, which is a sum over `mostPopularUpdates`.
+- **Fresh publishes** may show zeros for a short period while the metrics pipeline catches up.
+- **Installs are downloads, not launches**: the `installs` / "Launches" field counts users who downloaded the manifest and launch asset. A confirmed run only registers on the user's *next* update check (typically up to 24h later, depending on the app's update policy). So metrics lag the real-world state slightly.
+- **Crashes are self-reported**: `failedInstalls` / "Crashes" counts updates that errored during install/launch and were reported on the next update check. Crashes that don't trigger an update request (e.g. process kill before recovery) won't appear.
+
+## 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-update-insights" "<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.

package/bundled-skills/eas-update-insights/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EAS Update Insights"
+  short_description: "Paid EAS service. Check EAS Update health, adoption, crash rates, launch counts, payload size, and OTA vs embedded usage"
+  default_prompt: "Use $eas-update-insights to inspect published EAS Update with eas-cli, compare rollout health, gather update or channel metrics, parse JSON output, and gate releases on aggregate update performance."

package/bundled-skills/eas-update-insights/references/channel-insights-schema.md

@@ -0,0 +1,47 @@
+# `eas channel:insights` JSON schema
+
+Complete JSON output shape returned by `eas channel:insights --channel <name> --runtime-version <version> --json --non-interactive`.
+
+```json
+{
+  "channel": "production",
+  "runtimeVersion": "1.0.6",
+  "timespan": { "start": "...", "end": "...", "daysBack": 7 },
+  "embeddedUpdateTotalUniqueUsers": 2401,
+  "otaTotalUniqueUsers": 8312,
+  "mostPopularUpdates": [
+    {
+      "rank": 1,
+      "groupId": "abc123",
+      "message": "Fix checkout crash",
+      "platform": "ios",
+      "totalUniqueUsers": 4210
+    }
+  ],
+  "cumulativeMetricsAtLastTimestamp": [
+    { "id": "...", "label": "Embedded update", "data": 12345 },
+    { "id": "...", "label": "Embedded update failed installs", "data": 0 }
+  ],
+  "uniqueUsersOverTime": { "labels": ["..."], "datasets": [ { "id": "...", "label": "...", "data": [100, 200] } ] },
+  "cumulativeMetricsOverTime": { "labels": ["..."], "datasets": [ { "id": "...", "label": "...", "data": [10, 20] } ] }
+}
+```
+
+## Field reference
+
+| Path | Meaning |
+|---|---|
+| `channel` | The channel queried. |
+| `runtimeVersion` | The runtime version filter used. Channel insights are always scoped to a single runtime. |
+| `timespan.start` / `.end` / `.daysBack` | Window bounds (UTC ISO) and size in days. |
+| `embeddedUpdateTotalUniqueUsers` | Distinct users running the embedded (binary-bundled) build in the window. |
+| `otaTotalUniqueUsers` | Sum of `totalUniqueUsers` across `mostPopularUpdates`. May undercount if more than top-N updates are active (see caveat below). |
+| `mostPopularUpdates[]` | Top-N updates ranked by `totalUniqueUsers`. Each entry has `rank`, `groupId`, `message`, `platform`, `totalUniqueUsers`. |
+| `cumulativeMetricsAtLastTimestamp[]` | Snapshot totals at the end of the window, labelled (e.g., "Embedded update", "Embedded update failed installs"). |
+| `uniqueUsersOverTime` | Chart-shaped object with `labels` (dates) and `datasets` for plotting unique users over time. |
+| `cumulativeMetricsOverTime` | Chart-shaped object for plotting cumulative metrics over time. |
+
+## Caveats
+
+- `otaTotalUniqueUsers` is a sum of `mostPopularUpdates[].totalUniqueUsers`. If more OTA updates are active than the top-N the server returns, this figure undercounts true OTA reach.
+- A user running the same publish on both iOS and Android may be counted on each platform. Don't treat `uniqueUsers` as cross-platform-deduped.

package/bundled-skills/eas-update-insights/references/update-insights-schema.md

@@ -0,0 +1,69 @@
+# `eas update:insights` JSON schema
+
+Complete JSON output shape returned by `eas update:insights <groupId> --json --non-interactive`.
+
+```json
+{
+  "groupId": "03d5dfcf-736c-475a-8730-af039c3f4d06",
+  "timespan": {
+    "start": "2026-04-10T00:00:00.000Z",
+    "end": "2026-04-17T00:00:00.000Z",
+    "daysBack": 7
+  },
+  "platforms": [
+    {
+      "platform": "android",
+      "updateId": "019d72ca-...",
+      "totals": {
+        "uniqueUsers": 500,
+        "installs": 990,
+        "failedInstalls": 10,
+        "crashRatePercent": 1.0
+      },
+      "payload": {
+        "launchAssetCount": 4,
+        "averageUpdatePayloadBytes": 1115771
+      },
+      "daily": [
+        { "date": "2026-04-10T00:00:00.000Z", "installs": 182, "failedInstalls": 2 },
+        { "date": "2026-04-11T00:00:00.000Z", "installs": 195, "failedInstalls": 1 }
+      ]
+    },
+    {
+      "platform": "ios",
+      "updateId": "019d72ca-...",
+      "totals": { "uniqueUsers": 100, "installs": 1, "failedInstalls": 0, "crashRatePercent": 0 },
+      "payload": { "launchAssetCount": 4, "averageUpdatePayloadBytes": 1115771 },
+      "daily": [ { "date": "2026-04-10T00:00:00.000Z", "installs": 1, "failedInstalls": 0 } ]
+    }
+  ]
+}
+```
+
+## Field reference
+
+| Path | Meaning |
+|---|---|
+| `groupId` | The update group queried. |
+| `timespan.start` / `.end` | UTC ISO timestamps bounding the window. |
+| `timespan.daysBack` | Convenience field: size of the window in days. |
+| `platforms[]` | One entry per platform the group was published to (`ios`, `android`). |
+| `platforms[].updateId` | Platform-specific update ID (distinct from the group ID). |
+| `platforms[].totals.uniqueUsers` | Distinct users who ran this update in the window. |
+| `platforms[].totals.installs` | Launches / successful installs in the window. |
+| `platforms[].totals.failedInstalls` | Crashes / failed installs in the window. |
+| `platforms[].totals.crashRatePercent` | `failedInstalls / (installs + failedInstalls) * 100`. Zero when no installs. |
+| `platforms[].payload.launchAssetCount` | Number of assets the manifest references. |
+| `platforms[].payload.averageUpdatePayloadBytes` | Mean bundle size for the window. |
+| `platforms[].daily[]` | Per-day time series of installs and failed installs. |
+
+## `eas update:view <groupId> --insights --json`
+
+The `update:view --insights --json` command wraps the same insights payload:
+
+```json
+{
+  "updates": [ /* standard update:view entries */ ],
+  "insights": { /* same shape as eas update:insights above */ }
+}
+```