vybekiit 0.7.4 → 0.7.7

package/dist/global-skills/eas-observe/references/setup.md

@@ -23,6 +23,7 @@ Before installing, confirm all of the following:
 1. **An Expo account.** Sign up at [expo.dev/signup](https://expo.dev/signup) if needed.
 2. **Expo SDK 55 or later.** Run `npx expo-doctor` to check, and `npx expo install --fix` to update dependencies. SDK 56+ unlocks the newer `ObserveRoot` / `useObserve` API.
 3. **An EAS project.** The app must have `extra.eas.projectId` set in its app config. If not, run `eas init` to create one.
+4. **A development build or a production build.** `expo-observe` is a native library, so it does **not** work in Expo Go. Testing the integration requires a [development build](https://docs.expo.dev/develop/development-builds/introduction/).
 
 ## Step 1 — Install the library
 
@@ -162,6 +163,40 @@ export default ObserveRoot.wrap(RootLayout);
 
 `markInteractive()` is safe to call repeatedly — only the **first** call per session is recorded. If the app has more than one entry screen (onboarding, login, deep-link targets), call `markInteractive()` on **each one**. Otherwise TTI will be missing for sessions that open via a deep link to a screen without the call.
 
+### Custom params and route name
+
+`markInteractive()` accepts an options object. Use `params` to slice TTI by an app-specific dimension (cohort, tenant, feature-flag variant, cache hit). Use `routeName` to override the route the event is tagged with — useful when the logical screen name differs from the router path, when the route is dynamic, or when the app does not use Expo Router. Param values may be strings, numbers, booleans, or any JSON-serializable value.
+
+```tsx
+// SDK 56+: const { markInteractive } = useObserve();
+// SDK 55:  AppMetrics.markInteractive({ ... })
+markInteractive({
+  routeName: '/feed',
+  params: { tenant: 'acme', cohort: 'beta', cacheHit: true },
+});
+```
+
+### Declarative alternative: `<ObserveInteractiveMarker />` (SDK 56+)
+
+Instead of calling `markInteractive()` from an effect, render the marker component at the point the screen becomes interactive. It renders nothing and calls `markInteractive()` once on mount.
+
+```tsx
+import { ObserveInteractiveMarker } from 'expo-observe';
+
+function Feed({ items }) {
+  if (!items) return <Spinner />;
+
+  return (
+    <>
+      <FeedList items={items} />
+      <ObserveInteractiveMarker params={{ cacheHit: true }} />
+    </>
+  );
+}
+```
+
+The marker fires **once**, on mount, so its `params` are read from the first render. Changing them later has no effect and logs a development warning. When the params are only known later, call `useObserve().markInteractive(...)` imperatively instead.
+
 ## Step 4 — Build the app
 
 Metrics are collected from real builds, not from `expo start`:
@@ -180,7 +215,7 @@ To query metrics from the terminal with the EAS CLI, see [`./queries.md`](./quer
 
 ## Optional — per-route navigation metrics (SDK 56+)
 
-By default `expo-observe` records app-wide startup metrics only. To additionally get **per-route / per-screen** navigation metrics (`cold_ttr`, `warm_ttr`, and a per-navigation `tti`, each tagged with the route/screen), enable one of the navigation integrations. These require **SDK 56 or later**; on earlier SDKs they are silent no-ops. Query the resulting data with `eas observe:routes` (see [`./queries.md`](./queries.md)).
+By default `expo-observe` records app-wide startup metrics only. To additionally get **per-route / per-screen** navigation metrics (`cold_ttr`, `warm_ttr`, and a per-navigation `tti`, each tagged with the route/screen), enable one of the navigation integrations. These require **SDK 56 or later**; on earlier SDKs they are silent no-ops. Query the resulting data with `eas observe:routes`, or with `observe:metrics` / `observe:metrics-summary` under the CLI aliases `nav_cold_ttr`, `nav_warm_ttr`, and `nav_tti` (see [`./queries.md`](./queries.md)).
 
 Pick the integration that matches the app's router:
 
@@ -216,6 +251,8 @@ Docs: https://docs.expo.dev/eas/observe/integrations/expo-router/
 
 Events are tagged with the route **pattern** (e.g. `/(tabs)/sessions/[sessionId]`) so the dashboard buckets distinct param values together; the resolved `url` and `routeParams` are also included. Requires `expo-router` installed at runtime, or the integration no-ops.
 
+`router.prefetch()` does not count as a user navigation and never seeds a `cold_ttr` or `warm_ttr` measurement. The next user-driven navigation to a prefetched route emits `warm_ttr`, because the screen already rendered.
+
 ### React Navigation
 
 Docs: https://docs.expo.dev/eas/observe/integrations/react-navigation/
@@ -233,7 +270,9 @@ Requires `@react-navigation/native` 7.0.0 or later. Same `useObserve()` screen u
    });
    ```
 
-2. Replace the top-level `<NavigationContainer>` with `<ObserveNavigationContainer>` — a drop-in replacement that accepts the same props and forwards the same ref. If you pass a `linking` config it is used to resolve a human-readable screen path; otherwise the metric falls back to `route.name`.
+2. Connect the integration to the navigation tree. Which component you use depends on whether the app uses React Navigation's dynamic or static configuration. Both record the same per-screen metrics.
+
+   **Dynamic configuration** — replace the top-level `<NavigationContainer>` with `<ObserveNavigationContainer>`. It is a drop-in replacement that accepts the same props and forwards the same ref. If you pass a `linking` config it is used to resolve a human-readable screen path; otherwise the metric falls back to `route.name`.
 
    ```tsx
    import { ObserveNavigationContainer } from 'expo-observe/integrations/react-navigation';
@@ -243,8 +282,65 @@ Requires `@react-navigation/native` 7.0.0 or later. Same `useObserve()` screen u
    }
    ```
 
+   **Static configuration** — `createStaticNavigation()` renders the container for you, so there is nothing to replace. Create the navigation ref yourself, pass it to both `<Navigation>` and `<ObserveNavigationProvider>`, and the provider records the same timings by listening through that ref.
+
+   ```tsx
+   import { createStaticNavigation, useNavigationContainerRef } from '@react-navigation/native';
+   import { ObserveNavigationProvider } from 'expo-observe/integrations/react-navigation';
+
+   const Navigation = createStaticNavigation(RootStack);
+
+   export default function App() {
+     const navigationRef = useNavigationContainerRef();
+
+     return (
+       <ObserveNavigationProvider navigationRef={navigationRef}>
+         <Navigation ref={navigationRef} />
+       </ObserveNavigationProvider>
+     );
+   }
+   ```
+
+   `ObserveNavigationProvider` renders no container of its own, but it must be an ancestor of every screen so `useObserve()` works inside them. Pass the **same** ref to both elements; a ref that is not connected to a container emits no metrics.
+
+With React Navigation v7's default `lazy: true`, unfocused tabs stay unmounted, so their first focus records as `cold_ttr` rather than `warm_ttr`.
+
 In both integrations, `useObserve()` is safe to leave in place even when the integration is disabled or the router package is absent — it falls back to the global `markInteractive`.
 
+### Per-route event params
+
+Navigation events carry these params in addition to any custom ones passed to `markInteractive`:
+
+| Param | Type | Notes |
+|---|---|---|
+| `routeName` | string | Route pattern (`/(tabs)/sessions/[sessionId]`) with Expo Router, route-name path (`/Tabs/Sessions`) with React Navigation. Never contains param values. |
+| `url` | string | Resolved pathname. Expo Router only. |
+| `routeParams` | object | Resolved route params, e.g. `{ sessionId: 'abc' }`. |
+| `isAppLaunch` | boolean | `cold_ttr` only. `true` when measured from process start rather than from a navigation action. |
+| `urlHidden` | boolean | Present as `true` when a filtered param caused `url` to be omitted. See below. |
+
+### Filter sensitive params (SDK 57+)
+
+By default the integrations export the resolved URL and every serializable route and query param. If any of those carry sensitive values, list their keys in `filteredParams`:
+
+```tsx
+Observe.configure({
+  integrations: {
+    'expo-router': { filteredParams: ['userId', 'token'] },
+    // or: 'react-navigation': { filteredParams: ['userId', 'token'] },
+  },
+});
+```
+
+Filtered keys are removed from `routeParams`, and the event drops `url` in favor of `urlHidden: true`. `routeName` is unaffected, because it is a pattern and never contains param values.
+
+### Common integration mistakes
+
+- Calling `Observe.configure()` after mount, or toggling an integration flag mid-session, **throws**. Enable it at module scope.
+- `Calling markInteractive on unmounted screen` or `No metadata available for the current screen` means the call ran outside a screen component or after unmount. Move it into a `useEffect` inside the screen component.
+- Call `useObserve()` inside the screen component, not in a wrapper above it. A screen identity that changes between renders logs a warning.
+- With React Navigation, `markInteractive()` records only once the screen is focused. A call on an unfocused screen updates internal state but emits no `tti` event until focus.
+
 ## Optional — user-defined events (SDK 56+)
 
 Beyond the automatic startup and navigation metrics, you can record your own named events from anywhere in the app to track product moments — a completed onboarding, an exported report, a selected item. Use `Observe.logEvent(name, options?)`.
@@ -266,9 +362,10 @@ function handleOnboardingComplete() {
 | Parameter | Type | Required | Notes |
 |---|---|---|---|
 | `name` | `string` | yes | Stable, dot-separated identifier, e.g. `'report.exported'`. |
-| `options.attributes` | `Record<string, string \| number \| boolean \| array \| nested object>` | no | Structured context attached to the event. |
+| `options.attributes` | `Record<string, string \| number \| boolean \| array \| nested object>` | no | Structured context attached to the event. Other JS values (`Date`, `undefined`, functions) are dropped. |
 | `options.body` | `string` | no | Free-form message complementing the structured attributes. |
 | `options.severity` | `'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'` | no | Defaults to `'info'`. |
+| `options.displayName` | `string` | no | Human-friendly label, e.g. `'Onboarding completed'`. Used **only** in the dashboard's session timeline view; grouping still keys off `name`. |
 
 **Attributes** are the primary way to make an event queryable — attach the identifiers and measurements you'll want to filter or break down by:
 
@@ -306,12 +403,74 @@ User-defined events are persisted on-device, batched, and dispatched on the next
 
 User-defined events appear under the **Events** tab in the Observe dashboard, and are queryable from the terminal with `eas observe:events` — see [`./queries.md`](./queries.md).
 
+## Optional — error reporting
+
+`expo-observe` records errors as non-fatal `exception` log events alongside the performance metrics. They arrive by three paths, and they are **not** a replacement for a crash reporter such as Sentry — EAS Observe has no crash reporting yet.
+
+> These APIs ship in `expo-observe` but are not covered by the published docs yet. Verify the exports against the installed package version before relying on them.
+
+**1. Unhandled JS errors — automatic.** A global `ErrorUtils` handler is installed when the package is first imported, which is earlier than any `configure()` call, so errors thrown before configuration are still recorded. React Native's own behavior is unchanged: the red box in development and fatal termination in production still happen. Turn the recording off with `configure({ errorHandlingEnabled: false })`.
+
+**2. Render-phase errors — `<ObserveErrorBoundary>`.** Render errors never reach `ErrorUtils`, so a boundary is the only way to capture them with the React component stack. The boundary records the error and then renders `fallback` in place of the subtree.
+
+```tsx
+import { ObserveErrorBoundary } from 'expo-observe';
+
+<ObserveErrorBoundary
+  fallback={({ error, resetError }) => <ErrorScreen error={error} onRetry={resetError} />}>
+  <Feed />
+</ObserveErrorBoundary>;
+```
+
+`fallback` is required and accepts a React element, `null`, or a function receiving `{ error, resetError }`. `resetError()` clears the caught error and re-mounts the children, so they restart from a clean state. There is no capture-and-rethrow mode — a boundary always renders one of the three fallback forms. Errors that no boundary catches still reach the global handler.
+
+**3. Handled errors — `Observe.reportError(error)`.** Report failures your code caught and recovered from, which reach neither the global handler nor a boundary.
+
+```tsx
+try {
+  await syncCart();
+} catch (error) {
+  Observe.reportError(error);
+}
+```
+
+The value is normalized before it is sent: an `Error` contributes `name`, `message`, and `stack`; any other thrown value (a string, a plain object, a number) is stringified into the message with no stack. `reportError` never throws — it is called from a `catch` block, so a failure inside it must not turn a handled error into an unhandled one.
+
+## Optional — runtime configuration
+
+`Observe.configure()` controls collection and dispatch. Call it at module scope, before mount. Integration flags in particular cannot be toggled at runtime.
+
+| Option | Type | Default | What it does |
+|---|---|---|---|
+| `environment` | string | `process.env.NODE_ENV`, falling back to `'production'` | Metadata tag used to group metrics; filterable in the dashboard. Does not gate dispatch. |
+| `dispatchingEnabled` | boolean | `true` | Master switch. While `false`, pending metrics are dropped, not queued. |
+| `dispatchInDebug` | boolean | `false` | Dispatch metrics collected from debug builds. No effect on release builds. |
+| `sampleRate` | number | `undefined` (all installations) | Fraction of installations that dispatch, in `[0, 1]`. |
+| `errorHandlingEnabled` | boolean | `true` | Record unhandled JS errors as `exception` events. |
+| `integrations` | object | `undefined` | Opt in to `expo-router`, `react-navigation`, or a third-party integration. |
+
+**Network request monitoring is automatic and has no off switch.** `expo-observe` observes `URLSession` traffic on iOS and `OkHttpClient` traffic on Android from launch, and attaches a rollup of the launch window to the TTI event — including the **host** of the slowest request (see [`./metrics.md`](./metrics.md)). Observe's own uploads are excluded. No `configure()` option disables it as of `expo-observe` 57.0.9, so treat request hosts as data that leaves the device.
+
+**Sampling** is deterministic per installation: an installation is permanently in-sample or out-of-sample for a given rate, so the slice is stable across launches rather than a random subset of sessions. Out-of-sample installations drop pending metrics instead of accumulating them, so lowering the rate later does not retroactively send earlier sessions. Values outside `[0, 1]` are clamped. Sampling depends on `dispatchingEnabled`.
+
+**Manual flush.** Events dispatch automatically when the app backgrounds — on Android through a background worker once connectivity returns, on iOS when the app resigns active or is about to terminate. Call `await Observe.dispatchEvents()` to flush early, which is mainly useful while testing.
+
+**Custom endpoint.** EAS Observe sends OTLP over HTTP with a JSON payload, posting to `<endpointUrl>/<project-id>/v1/metrics` and `<endpointUrl>/<project-id>/v1/logs`. Point it at any OpenTelemetry-compatible backend or collector through the **app config**, not `configure()`:
+
+```json
+{ "expo": { "extra": { "eas": { "observe": { "endpointUrl": "https://your-endpoint.com" } } } } }
+```
+
+The URL is baked into the native layer at build time, so run `npx expo prebuild` and rebuild after changing it. If the backend expects standard OTLP paths without the project-ID prefix, route through a collector.
+
 ## Quick checklist
 
-- [ ] SDK ≥ 55, EAS project linked.
+- [ ] SDK ≥ 55, EAS project linked, development or production build (not Expo Go).
 - [ ] `expo-observe` installed via `npx expo install`.
 - [ ] Root component exported through `AppMetricsRoot.wrap(...)` (SDK 55) or `ObserveRoot.wrap(...)` (SDK 56+).
 - [ ] `markInteractive()` called from every entry screen once it is genuinely interactive — global `AppMetrics.markInteractive()` on SDK 55, or `useObserve()` hook on SDK 56+.
-- [ ] (Optional, SDK 56+) Per-route metrics enabled via `Observe.configure({ integrations: { ... } })`, plus `<ObserveNavigationContainer>` for React Navigation.
+- [ ] (Optional, SDK 56+) Per-route metrics enabled via `Observe.configure({ integrations: { ... } })`, plus `<ObserveNavigationContainer>` (dynamic) or `<ObserveNavigationProvider>` (static) for React Navigation.
+- [ ] (Optional, SDK 57+) Sensitive route/query params listed in `filteredParams`.
 - [ ] (Optional, SDK 56+) User-defined events emitted via `Observe.logEvent(name, { attributes })` with stable, lowercase, dot-separated names and no PII.
+- [ ] (Optional) `<ObserveErrorBoundary>` around risky subtrees and `Observe.reportError` in recovery paths.
 - [ ] New build produced with `eas build` and metrics visible in the Observe dashboard.

package/dist/global-skills/eas-observe/references/third-party.md

@@ -0,0 +1,136 @@
+# Add an EAS Observe integration to a third-party package
+
+This reference is for **package authors**, not app developers. It describes how a library ships an optional EAS Observe integration so that apps using the library get events about problems that application code cannot detect on its own.
+
+> Source: https://docs.expo.dev/eas/observe/integrations/third-party/ — consult this page for the latest guidance.
+
+App-side setup lives in [`./setup.md`](./setup.md). Querying the resulting events is in [`./queries.md`](./queries.md).
+
+## When to use this
+
+Report actionable issues the developer can fix. Good candidates:
+
+- An image decoded at far higher resolution than the device screen needs.
+- A background task that exceeds its expected duration.
+- A native resource that loads slowly.
+
+Do not use it for general product analytics or for anything the app author could log themselves.
+
+## Requirements
+
+- **Expo SDK 57 or later.** `Observe.registerIntegration()` is not available earlier.
+- The consuming app must already have `expo-observe` installed and a build produced.
+
+## Step 1 — Depend on `expo-observe` optionally
+
+The package must keep working when `expo-observe` is absent. Declare it as an **optional peer dependency** plus a dev dependency for types and tests. Never make it a required runtime dependency.
+
+```json
+{
+  "peerDependencies": { "expo-observe": ">=57.0.0" },
+  "peerDependenciesMeta": { "expo-observe": { "optional": true } },
+  "devDependencies": { "expo-observe": "^57.0.0" }
+}
+```
+
+Load it with `require()` inside `try/catch`, and type it with `typeof import()` so the types survive:
+
+```ts
+// observe.ts
+let observeModule: typeof import('expo-observe') | undefined;
+
+try {
+  observeModule = require('expo-observe') as typeof import('expo-observe');
+} catch {
+  // The integration stays disabled when expo-observe is not installed.
+}
+```
+
+## Step 2 — Declare the integration config
+
+Use declaration merging to add your integration key to `ObserveIntegrationsConfig`:
+
+```ts
+// observe.types.ts
+export type YourPackageIntegrationConfig = {
+  thresholdMs?: number;
+};
+
+declare module 'expo-observe' {
+  interface ObserveIntegrationsConfig {
+    'your-package'?: boolean | YourPackageIntegrationConfig;
+  }
+}
+```
+
+Export this declaration from the package entry point so TypeScript loads it when the app imports your package. App developers then enable it the same way they enable the first-party integrations:
+
+```tsx
+Observe.configure({
+  integrations: {
+    'your-package': true,
+    // or, with options:
+    // 'your-package': { thresholdMs: 1500 },
+  },
+});
+```
+
+## Step 3 — Register the integration
+
+`Observe.registerIntegration(name, callback)` invokes the callback once, when the named integration config becomes available. The callback does not run when the key is omitted or set to `false`.
+
+```ts
+// observe.ts
+export function initObserveIntegration() {
+  // The `typeof window` check skips initialization during server-side rendering on web.
+  if (typeof window !== 'undefined' && observeModule) {
+    const { Observe } = observeModule;
+
+    Observe.registerIntegration('your-package', config => {
+      if (config) {
+        enableObserveIntegration(config === true ? {} : config);
+      }
+    });
+  }
+}
+```
+
+Call the initializer from the package entry point:
+
+```ts
+// index.ts
+import { initObserveIntegration } from './observe';
+
+export type { YourPackageIntegrationConfig } from './observe.types';
+
+initObserveIntegration();
+```
+
+Note the `config === true` normalization: the key accepts either a boolean or an options object, so collapse `true` to `{}` before using it.
+
+## Step 4 — Log events
+
+Emit through `Observe.logEvent()` when the package detects an actionable issue. Guard on both module presence and enablement, so a disabled integration costs nothing.
+
+```ts
+export function logExpensiveOperation(durationMs: number, thresholdMs: number) {
+  if (!observeModule || !enabled) {
+    return;
+  }
+
+  const { Observe } = observeModule;
+
+  Observe.logEvent('your-package.expensive-operation', {
+    severity: 'warn',
+    body: 'Reduce the work performed by this operation or increase the configured threshold.',
+    attributes: { durationMs, thresholdMs },
+  });
+}
+```
+
+Naming rules, matching the app-side event conventions in [`./setup.md`](./setup.md):
+
+- Lowercase, dot-separated, with **your package name as the first segment**: `your-package.expensive-operation`.
+- Keep names stable. The dashboard groups by exact name.
+- No PII in names, attribute keys, or attribute values.
+- Use `severity` to separate warnings from errors, and `body` for the remediation hint. The attributes carry the measurements.

package/dist/global-skills/eas-simulator/SKILL.md

@@ -3,7 +3,7 @@ name: eas-simulator
 description: "EAS service (paid). Run and control a user's app on a remote iOS/Android simulator hosted on EAS cloud. Read before running any `eas simulator:*` commands - it has the current syntax for this experimental API. Use whenever the user needs a simulator they can't run locally - 'run my app on a cloud simulator', 'use eas simulator to run/install/screenshot my app', 'I'm on Linux/Cursor and need an iOS device', 'no sim on this box / headless CI', 'let an agent click through my app and screenshot it', 'test my dev build on a remote sim with live reload', 'stream a sim to my browser' - even when they don't say 'EAS Simulator' or 'cloud'. On a host WITHOUT a local simulator (Linux, CI, cloud sandbox) it's the default; on macOS, do NOT auto-trigger for a plain 'run on the simulator' - use it only for a cloud/remote/shareable sim, an iOS version they lack, or an agent-driven session. NOT for local sims (expo run:ios, Xcode, Android Studio), EAS Build/Update, web preview, or physical devices."
 version: 1.0.0
 license: MIT
-allowed-tools: "Bash(npx *eas-cli@*), Bash(npx *agent-device@*), Bash(npx expo *), Bash(eas *), Bash(expo *), Bash(xcodebuild*), Bash(pod*)"
+allowed-tools: "Bash(npx *eas-cli@*), Bash(npx *agent-device@*), Bash(npx expo *), Bash(eas *), Bash(expo *), Bash(xcodebuild*), Bash(pod*), Bash(argent *), Bash(ffmpeg*)"
 ---
 
 # EAS Simulator
@@ -20,7 +20,7 @@ The frontmatter `description` carries the trigger phrases. In short: use this to
 
 ## Cloud vs local: decide this first
 
-- **Non-macOS** (Linux / CI / cloud sandbox like Cursor Cloud, detect via `uname -s` ≠ `Darwin`): the only way to get a sim — **just proceed.**
+- **Non-macOS** (Linux / CI / cloud sandbox like Cursor Cloud, detect via `uname -s` ≠ `Darwin`): the only way to get a sim — **proceed, once you've confirmed access** (see *Check availability first* below).
 - **macOS:** local sims exist and a cloud session costs money + latency, so **ask first** ("a remote cloud sim — to share a live preview, offload, or test an iOS version you lack — or just run locally?") unless the user explicitly said cloud/remote/shareable.
 - Always honor an explicit choice; for "run it locally" hand off to `expo run:ios` / Xcode.
 
@@ -41,6 +41,23 @@ fi
 - A controller to drive the device. This skill uses **agent-device** (open source, MIT), run on demand via `npx agent-device@latest` — nothing globally installed. **argent** is an alternative (`--type argent` in `simulator:start`); see [references/controllers.md](./references/controllers.md).
 - **`.env.eas-simulator`** is written/managed by eas-cli (not this skill): it holds the session id (`EAS_SIMULATOR_SESSION_ID`) + the daemon URL/**token**, so `get`/`stop`/`exec` default to that session (usually **omit `--id`**; pass `--id <id>` to target another). It carries a **token → keep it gitignored** (eas-cli marks it "do not commit" but may not add the ignore rule, and a fresh app's `.gitignore` won't cover it — add `.env.eas-simulator` if missing).
 - `--max-duration-minutes` is paid-plan only; otherwise a default applies.
+- **The command blocks assume a POSIX shell** (bash/zsh) — `printf`, `lsof`, `$(seq …)` loops won't run in cmd/PowerShell. On Windows, run them in WSL or Git Bash, or translate as you go (the `eas-cli`/`agent-device` invocations themselves are cross-platform).
+
+## Check availability first
+
+EAS Simulator is a **limited-access** EAS feature that is still rolling out, so it isn't enabled on every account. Confirm access **before** starting a session — this is a read-only check: no session, no billing.
+
+```bash
+npx --yes eas-cli@latest simulator:availability --json
+# → {"available": true, ...}  enabled → continue to the core loop
+# → {"available": false, ...} not enabled → do NOT start a session
+```
+
+If it's **not** available, don't call `simulator:start` (it will fail). Instead, hand off gracefully so you keep making progress without this skill:
+- Tell the user EAS Simulator isn't available on their account yet — it's coming soon.
+- Fall back to their normal local path for the actual goal — `expo run:ios` / Xcode / Android Studio for a local sim/emulator, an EAS Build, or whatever else fits. Don't dead-end on the cloud sim; the request was almost never "use EAS Simulator specifically."
+
+(If `simulator:availability` isn't recognized, the CLI is too old — upgrade, or treat a `not enabled for this account` error from `simulator:start` the same way: stop and fall back.)
 
 ## The core loop (always the same)
 
@@ -49,7 +66,8 @@ A session is: **start → (install your app) → drive → stop.** `eas-cli` own
 ```bash
 # 1. Start a session (boots the remote sim + agent-device daemon; writes .env.eas-simulator).
 printf '# managed by eas-cli\n' > .env.eas-simulator   # clear any stale session first
-npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --non-interactive
+npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --non-interactive \
+  --name "Checkout flow screenshots"   # always name it — see 'Always name the session'
 #    Then confirm it's live: simulator:get --json → status IN_PROGRESS (bounded poll in run-your-app.md).
 
 # 2. Drive it through `exec` (loads the session env, then runs the command you give it).
@@ -72,14 +90,37 @@ To **watch** it live, hand the user the `webPreviewUrl` that `start` prints (an
 
 `start` also prints a job-run URL.
 
+## Always name the session
+
+Pass `--name "<description>"` on every `simulator:start`. The name appears in `simulator:list`, `simulator:get`, and on the **Simulator sessions** page on expo.dev, where it replaces the generic title on each row. Unnamed, every row reads "Simulator session" over a random id — a wall of identical entries nobody can navigate. Write the name for a **human scanning that list days later**, not for yourself during this run.
+
+Write what the session is *for*, in a few plain words:
+
+```bash
+--name "Checkout flow screenshots"     # what you did
+--name "Dev build — dark mode fix"     # what you were testing
+--name "Login repro for issue 412"     # why it exists
+```
+
+Rules:
+- Derive it from the user's request, not from the mode or the tooling. `Mode C session`, `agent-device ios`, and `test` say nothing.
+- **Length: aim for 3–6 words, ~40 characters, and treat 50 as the practical limit.** It renders as a single-line title in a narrow table column, so a long name clips. The API accepts up to **255 characters** and rejects an empty/whitespace-only name, but 255 is a ceiling you never approach, not a target. One noun phrase, no sentences.
+- Be specific within that budget. Include a ticket or PR number when there is one.
+- **Sentence case:** capitalize the first word only, and leave identifiers in their real casing (`Dev build for expo-router v4`, `Repro for EXPO-1234`). It's a row title, so no Title Case, no all-lowercase, and no trailing period.
+- **Don't repeat what the table already shows.** Every row already displays the session id, platform, start time, duration, and who created it — so no ids, no `iOS`, no dates, no your-own-name. Spend the whole budget on what those columns can't say: the purpose.
+- If the user names it, use their name as-is.
+- Sessions are per-run, so name each new one for that run. Don't reuse an old name for different work.
+
+`--name` is newer than `simulator:start` itself, so an older installed `eas-cli` can reject it. If that happens, run via `npx --yes eas-cli@latest` or upgrade; as a last resort, retry once without `--name` (the session starts unnamed). See [references/troubleshooting.md](./references/troubleshooting.md).
+
 ## Commands at a glance
 
 | Command | Purpose |
 |---|---|
-| `npx --yes eas-cli@latest simulator:start --platform ios\|android [--type agent-device\|argent\|serve-sim] [--package-version X] [--max-duration-minutes N] [--non-interactive] [--json]` | Create a session; boot the sim + controller; write `.env.eas-simulator`; print `webPreviewUrl` + job-run URL |
+| `npx --yes eas-cli@latest simulator:start --platform ios\|android --name "<description>" [--type agent-device\|argent\|serve-sim] [--package-version X] [--max-duration-minutes N] [--non-interactive] [--json]` | Create a session; boot the sim + controller; write `.env.eas-simulator`; print `webPreviewUrl` + job-run URL. **Always pass `--name`** (see *Always name the session*). **`--json` suppresses the `.env.eas-simulator` write** — omit it for the `exec` flow, or set the env yourself from `remoteConfig`. |
 | `npx --yes eas-cli@latest simulator:exec <cmd> [args…]` | Load `.env.eas-simulator`, then run `<cmd>` with that env. The bridge to the controller. |
-| `npx --yes eas-cli@latest simulator:get [--id] [--json]` | Session status + connection details. **Use this to confirm readiness** (see *Operating principles*). |
-| `npx --yes eas-cli@latest simulator:list [--status …] [--type …] [--platform …]` | List an app's sessions |
+| `npx --yes eas-cli@latest simulator:get [--id] [--json]` | Session status + connection details, including the session `--name`. **Use this to confirm readiness** (see *Operating principles*). |
+| `npx --yes eas-cli@latest simulator:list [--status …] [--type …] [--platform …]` | List an app's sessions by name — this is what the `--name` you pass to `start` is for |
 | `npx --yes eas-cli@latest simulator:stop [--id]` | Stop a session (idempotent) |
 
 ## Running the user's app — pick a mode
@@ -109,16 +150,19 @@ Quick decision — **default to C; A and B are explicit-only:**
 
 | Verb | Does |
 |---|---|
-| `apps --platform ios` | List installed apps (the blank sim shows none) |
+| `apps --platform ios` | List user-installed apps (the blank sim shows none); add `--all` to include system apps |
 | `install <appId> <path> --platform ios` | Install a local `.app` (uploads it) |
 | `install-from-source <url> --platform ios` | Install from a URL — the VM downloads it (use for EAS artifacts) |
-| `open <appId\|deep-link> --platform ios` | Launch an app (bundle id) or follow an app **deep link** (`exp+slug://…`). **Not** for the `webPreviewUrl` — that's a browser preview for the user, never the device. |
+| `open <appId\|deep-link> --platform ios` | Launch an app (bundle id) or follow an app **deep link** (`exp+slug://…`). A first-time deep link raises a system **"Open in '<app>'?"** dialog — expect it (don't burn a snapshot discovering it) and `press 'label="Open"'` to hand off; it can be slow, so bound it with agent-device's own `--timeout` (e.g. `press 'label="Open"' --timeout 120000`) — **not** a shell `timeout` wrapper (macOS has no `timeout` binary). (Mode C sidesteps this dialog for the Metro-connect link via "Enter URL manually" — see run-your-app.md.) **Not** for the `webPreviewUrl` — that's a browser preview for the user, never the device. |
 | `snapshot -i` | Interactive accessibility tree → `@e1`-style refs |
 | `press <ref\|selector>` | Tap (e.g. `press @e2` or `press 'label="Open"'`) — **the tap verb is `press`, not `tap`** |
 | `fill <ref> "text"` | Type into a field |
 | `screenshot <path>` | Capture the screen to a local PNG (downloaded from the daemon) — requires an app to be open (`open` first) |
+| `record start` / `record stop <path>` | Record the screen to a video — use this for **motion** (animations, gestures, transitions, timing), which a single screenshot can't capture |
 | `metro prepare` / `metro reload` | Point a dev client at Metro / reload (Mode C) |
 
+**Screenshots vs. video.** Default to `screenshot` for static state, but for anything that *moves* — an animation, a transition, a gesture, a timing/jank question — **record a video and inspect the frames** instead; a still can't prove motion. Both controllers record (agent-device `record start`/`stop`, argent `screen-recording-start`/`stop`). Recordings sample at ~30fps — enough to see visible jank, not to prove sub-frame 60/120Hz hitches. For **timing** specifically, argent drops static frames by default (turn `trimStatic` off) — that plus other per-controller gotchas are in [references/controllers.md](./references/controllers.md).
+
 For the full verb set and the `argent` controller alternative, see [references/controllers.md](./references/controllers.md).
 
 ## Operating principles
@@ -128,10 +172,10 @@ The non-obvious mental model worth internalizing. Specific error→fix lookups (
 1. **Establish ground truth, then reset — don't patch-loop.** Never assume an existing session or Metro is yours or healthy. Before driving, confirm:
    - **cwd** — you're in the intended Expo project dir (a misdirected `start`/`exec` sessions the *wrong app* + drops a stray `.env.eas-simulator`; `pwd` / check `app.json`).
    - **session live** — `IN_PROGRESS` via `simulator:get --json` (a stopped session keeps its id + `remoteConfig`, so the dotenv alone isn't proof).
-   - **one Metro on `:8081`** — reuse if it's yours, else free the port before starting (run-your-app.md).
+   - **Metro on its own port** — reuse only if you started it this session; else start one on a free port (`--port <N>`, e.g. 8082), don't kill another server to reclaim `:8081` (run-your-app.md).
    - **build fits intent** — a **release build can't live-reload**; if live edits are wanted and a release build is installed, **install the dev build, don't reconnect**.
 
-   If current code isn't rendering after your **first** connect, stop poking live state: **reset to baseline** (stop session → clear dotenv → kill Metro) and redo the mode **once**; a second failure → stop and report. Never restart Metro in place, reconnect more than once, rebuild the native client to fix a JS/connection problem, or surface a preview URL while state is unknown. (A daemon drop — `ERR_NGROK_3200` / `Remote daemon is unavailable` — is the same: reset, don't retry.)
+   If current code isn't rendering after your **first** connect, stop poking live state: **reset to baseline** (stop session → clear dotenv → kill your Metro) and redo the mode **once**; a second failure → stop and report. Never restart Metro in place, reconnect more than once, rebuild the native client to fix a JS/connection problem, or surface a preview URL while state is unknown. (A daemon drop — `ERR_NGROK_3200` / `Remote daemon is unavailable` — is the same: reset, don't retry.)
 2. **`exec` is a wrapper, not a driver.** `simulator:exec` loads `.env.eas-simulator` and spawns the command you pass; the device verbs come from the controller (`npx agent-device@latest`). There is no `simulator:tap`.
 3. **Act immediately; don't park an idle session.** Sessions are short-lived — install and drive right after `start`. Leaving one idle drops the tunnel/daemon (→ reset, per #1).
 4. **Stop on every exit path (billing) and reset the dotenv.** `--non-interactive` doesn't auto-stop, and a forgotten session bills until stopped. Don't `start` again to "retry" a slow boot — that orphans a second billed session.
@@ -149,8 +193,16 @@ printf '# managed by eas-cli\n' > .env.eas-simulator   # clear the stale session
 
 ## References
 
-- [references/run-your-app.md](./references/run-your-app.md) — full tested command sequences for modes A, B, and C (read before running a mode).
+- [references/run-your-app.md](./references/run-your-app.md) — full command sequences for modes A, B, and C (read before running a mode).
 - [references/controllers.md](./references/controllers.md) — agent-device verb reference and the `argent` alternative.
 - [references/troubleshooting.md](./references/troubleshooting.md) — concrete errors and fixes.
 
 Source of truth: Expo docs and the `eas` / `agent-device` CLIs (`npx --yes eas-cli@latest simulator:* --help`, `agent-device --help`). This skill teaches how to apply them; it doesn't replace them.
+
+## 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-simulator" "<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/dist/global-skills/eas-simulator/references/controllers.md

@@ -22,13 +22,31 @@ EAS-specific notes:
 - **`press`, not `tap`.** The tap verb is `press` — `tap` is not a verb.
 - **`snapshot -i` is slow on iOS** — tens of seconds is normal; wait for it.
 - **`install` uploads** a local binary to the daemon; **`install-from-source`** has the VM download from a URL (use for EAS artifacts — avoids a large upload).
-- **Proven in this skill's flows:** `apps`, `install`, `install-from-source`, `open`, `snapshot -i`, `press`, `fill`, `screenshot`. Others (`gesture`/`scroll`/`logs`/`record`/`network`/`perf`/`metro`) are real in the CLI but not exercised here — confirm via `<verb> --help` before relying on them.
+- **Exercised against a live session:** `apps`, `install`, `install-from-source`, `open`, `snapshot -i`, `press`, `fill`, `screenshot`, `scroll`, `gesture` (needs a preset, e.g. `gesture swipe left`), `logs`, `record` (`start`/`stop <path>`), `network`, `perf`. `metro` (`prepare`/`reload`) is the Mode C dev-client bridge. Pass `--platform ios`; run `<verb>` with no args to see its required subcommand/args.
 
 ## argent (alternative)
 
 `npx --yes eas-cli@latest simulator:start --type argent` provisions an argent remote session. The connection config it returns is different (`ARGENT_TOOLS_URL` / `ARGENT_AUTH_TOKEN`).
 
-**argent sessions cannot install apps today.** `--type argent` provisions only an argent daemon on the VM — there is no agent-device daemon, so agent-device install commands don't apply. Use argent to drive an app that is already on the sim (e.g. start with `--type agent-device` to install, then switch; or use an EAS build with `install-from-source` via an agent-device session first).
+**Invoking argent — run its tools directly.** Drive argent by running its tools directly — `argent run <tool> --udid <udid> …` (with `argent link` or the env-var config below) — where flags work (the examples here use this path); or via its MCP server, which passes structured params. Heads-up (flagged elsewhere, not reproduced in our own runs): routing an `argent run` call through `npx --yes eas-cli@latest simulator:exec` can **strip the `--flag` arguments**, so the tool runs with no options and fails confusingly. If you must go through `simulator:exec`, wrap it in `sh -c` and pass one `--args` JSON blob instead of flags: `npx --yes eas-cli@latest simulator:exec sh -c 'argent run <tool> --args "{\"udid\":\"<udid>\", …}"'`. argent's gesture tools take **normalized 0.0–1.0** coordinates, not pixels — check its help for the exact input shape.
+
+**Installing apps in an argent session.** `--type argent` provisions only an argent daemon on the VM — there is no agent-device daemon, so agent-device install verbs don't apply. Install a local build with argent's own `reinstall-app` (tar-upload):
+
+```bash
+argent run reinstall-app --udid <udid> --bundleId <bundle-id> --appPath ./MyApp.app
+```
+
+Whenever the tools client is routed to a remote tool-server, it tars the local bundle and streams it up automatically — no extra flag. "Remote" covers both `argent link` and the env-var MCP config (`ARGENT_TOOLS_URL`), so this works in sandboxed shells too. It's a registry tool, so the MCP server exposes it identically — same call by CLI or MCP. Works for iOS `.app` (a directory), Android `.apk`, and Vega `.vpkg`; the client prints an upload line on stderr.
+
+Needs argent ≥ 0.16.0 (the release that adds tar-upload) — verify with `argent --version`. On older versions `reinstall-app` resolves `--appPath` on the VM only, so a local path fails; drive an app already on the sim instead.
+
+**System dialogs on argent (e.g. the first-time deep-link "Open in '<app>'?").** argent's UI queries (`describe` / `await-ui-element`) may not see system dialogs / native modals — a screenshot shows the dialog, but element lookups time out. When that happens, argent surfaces a hint with the fix (today that's a `boot-device --force` to switch its AX backend); follow the hint, then locate and tap "Open". There's no single press-with-timeout — you wait for the element, then tap it. Use argent's own command help for the exact tools and flags.
+
+**Recording video on argent (`screen-recording-start`/`stop`).** The gotcha to know: argent **trims static stretches by default**, which drops the very frames you're measuring — turn that off when you care about cadence or timing (see argent's help for the flag). Recordings also carry a burned-in "Argent" watermark that can't be disabled on a hosted session — fine for diagnosis, mind it before sharing publicly. The stop call returns a video already downloaded locally; extract frames with `ffmpeg` (may need installing) to inspect motion frame by frame. The capture samples at ~30fps, so it shows visible jank but can't prove or disprove sub-frame hitches on 60/120Hz content.
+
+**Screenshot resolution and token cost.** Screenshots cost context tokens once the agent reads them, so resolution is a real tradeoff. **argent's `screenshot` has two independent levers.** `scale` sets the image resolution and defaults **low** (too coarse to judge layout), so pass a larger scale when you need to **read** the UI. `includeImageInContext:false` keeps an image **out of the agent's context entirely** (zero token cost) — use that for a baseline you'll only **diff** later, and keep *that* one at full resolution so the pixel diff stays accurate. So: scale down images you actually read; drop unread ones with `includeImageInContext`, don't just shrink them. Exact flags and the current default: argent's help.
+
+**agent-device** screenshots default to full resolution — a crisp PNG you read from disk, token-heavier for its size, so match the capture to the question. From **v0.20.6** it gains the same lever argent has and drops the old one: `screenshot --scale <0.01–1>` proportionally resizes both dimensions (`1` = full resolution), with a token-conscious default via `AGENT_DEVICE_SCREENSHOT_SCALE` (or `screenshotScale` in config) that an explicit `--scale` overrides — keep it unset or `1` for pixel-diff baselines; the former `--max-size` is removed (older calls refused with migration guidance). Verify the version with `agent-device --version`. One caveat for remote sessions: the resize runs on the daemon, so a newer client against an older EAS session daemon can have `--scale` silently ignored and get full-res back.
 
 **Connecting via MCP (Cursor, Claude Code, Codex, and others).** Install the CLI globally first — the package is `@swmansion/argent`, not `argent`:
 
@@ -65,3 +83,4 @@ MCP config file location: `.cursor/mcp.json` (Cursor), `.claude/mcp.json` (Claud
 
 **Known issues:**
 - `argent init --help` launches an interactive wizard regardless of the flag — use `--yes` to skip it, or read the package source for non-interactive flags.
+- Re-running `argent link` against an already-linked URL **without `--yes`** reports "Already linked. No changes." and keeps the old token — every call then fails with `401 Unauthorized`. Always pass `--yes` (as above) so a rotated token is actually written.

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

@@ -13,7 +13,10 @@ In all modes, the session is started the same way and driven through `npx --yes
 printf '# managed by eas-cli\n' > .env.eas-simulator
 
 # Start (no --json, so it writes .env.eas-simulator). It boots the sim + agent-device daemon.
-npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --non-interactive
+# --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`:
@@ -68,7 +71,7 @@ The `install` here **uploads** the (~90MB) `.app` to the remote daemon over the
 
 ```bash
 npx --yes eas-cli@latest build:list --platform ios --profile <your-sim-profile> --status finished --json | \
-  head -20   # look for a sim build whose fingerprint matches current source
+  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.
@@ -138,14 +141,16 @@ LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 xcodebuild \
   -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build-debug build
 DEVAPP=ios/build-debug/Build/Products/Debug-iphonesimulator/<App>.app
 
-# 2. Start Metro with tunnel v2 — exactly ONE instance. First check :8081:
-#    `curl -sf localhost:8081/status` answers AND it's your Metro → reuse it, skip this step.
-#    Port taken but NOT yours → `PIDS=$(lsof -ti:8081); [ -n "$PIDS" ] && kill $PIDS` BEFORE starting
-#    (relaunching onto an occupied 8081 is the "port already in use" clash). A bare `&` won't survive across agent
-#    shell calls — use a long-lived/background run or a separate terminal. tunnel v2 (durable-object,
-#    not ngrok) works from robot/cloud agents where plain --tunnel is blocked.
-EXPO_UNSTABLE_TUNNEL_V2=1 npx expo start --tunnel --port 8081
-#    → note the deep link exp+<slug>://<host>.on.expo.app; the manifest URL is https://<host>.on.expo.app
+# 2. Start Metro with tunnel v2 on its OWN port — don't force :8081 or kill anything to reclaim it.
+#    Each `expo start --tunnel` gets its own unique tunnel URL, so a second Metro never has to fight
+#    for the first one's port. Pick a free high port with `--port <N>` (e.g. 8082). Only reuse a
+#    running Metro if YOU started it this session — there's no command to prove ownership, so when
+#    unsure just start a new one on another port; never kill someone else's server. A bare `&` won't
+#    survive across agent shell calls — use a long-lived/background run or a separate terminal. tunnel
+#    v2 (durable-object, not ngrok) works from robot/cloud agents where plain --tunnel is blocked.
+EXPO_UNSTABLE_TUNNEL_V2=1 npx expo start --tunnel --port <N>
+#    → capture the tunnel/manifest URL + deep link it prints (format like https://<host>.on.expo.app).
+#      The port is NOT in the URL, so read it from stdout — `--port` only identifies the local process.
 
 # 3. Start a session, install the dev build, then connect it to Metro.
 #    RELIABLE path = "open the dev client, then Enter URL manually". The deep-link + system "Open in
@@ -163,7 +168,7 @@ npx --yes eas-cli@latest simulator:exec npx agent-device@latest open dev.example
 #    b) point it at your remote Metro via "Enter URL manually":
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest press 'label="Enter URL manually"'
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest snapshot -i          # get the text-field ref
-npx --yes eas-cli@latest simulator:exec npx agent-device@latest fill @<field> "https://<host>.on.expo.app"
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest fill @<field> "<manifest URL Metro printed in step 2>"   # e.g. https://<host>.on.expo.app
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest press 'label="Connect"'
 
 #    c) first-run dev menu → Reload to fetch the bundle (first build+transfer over the tunnel ~40-60s):