vybekiit 0.7.4 → 0.7.7

package/dist/global-skills/claimable-postgres/SKILL.md

@@ -8,8 +8,19 @@ description: >-
   include: "quick postgres", "temporary postgres", "no signup database",
   "no credit card database", "instant DATABASE_URL", "npx neon-new", "neon.new",
   "neon.new API", "claimable postgres API".
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/claimable-postgres
 ---
 
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
+
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
+
+```bash
+npx skills add neondatabase/agent-skills --skill neon
+```
+
 # Claimable Postgres
 
 Instant Postgres databases for local development, demos, prototyping, and test environments. No account required. Databases expire after 72 hours unless claimed to a Neon account.
@@ -34,6 +45,55 @@ For other methods (CLI, SDK, Vite plugin), see [Which Method?](#which-method) be
 - **Vite plugin** (`vite-plugin-neon-new`): Auto-provisions on `vite dev` if `DATABASE_URL` is missing. Use when the user has a Vite project.
 - **Browser**: User cannot run CLI or API. Direct to https://neon.new.
 
+## Auto-provisioning
+
+If the agent needs a database to fulfill a task (e.g. "build me a todo app with a real database") and the user has not provided a connection string, provision one via the API and inform the user. Include the claim URL so they can keep it.
+
+## Agent Workflow
+
+### API path
+
+1. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
+2. **Provision:** POST to `https://neon.new/api/v1/database` with `{"ref": "agent-skills"}`.
+3. **Parse response:** Extract `connection_string`, `claim_url`, and `expires_at` from the JSON response.
+4. **Write .env:** Write `DATABASE_URL=<connection_string>` to the project's `.env` (or the user's preferred file and key). Do not overwrite an existing key without confirmation.
+5. **Seed (if needed):** If the user has a seed SQL file, run it against the new database:
+   ```bash
+   psql "$DATABASE_URL" -f seed.sql
+   ```
+6. **Report:** Cover every item in the [Output Checklist](#output-checklist).
+7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`).
+
+### CLI path
+
+1. **Check .env:** Check the target `.env` for an existing `DATABASE_URL` (or chosen key). If present, do not run. Offer remove, `--env`, or `--key` and get confirmation (see [Pre-run Check](#pre-run-check)).
+2. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
+3. **Gather options:** Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication).
+4. **Run:** Execute with `@latest --yes` plus the confirmed options. Always use `@latest` to avoid stale cached versions. `--yes` skips interactive prompts that would stall the agent.
+   ```bash
+   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
+   ```
+5. **Verify:** Confirm the connection string was written to the intended file.
+6. **Report:** Cover every item in the [Output Checklist](#output-checklist).
+7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`).
+
+### Output Checklist
+
+Always report:
+
+- Where the connection string was written (e.g. `.env`)
+- Which variable key was used (`DATABASE_URL` or custom key)
+- The claim URL (from `.env` or API response)
+- That unclaimed databases are temporary (72 hours): the database works now, and claiming within 72 hours keeps it permanently
+
+## Safety and UX Notes
+
+- Do not overwrite existing env vars. Check first, then use `--env` or `--key` (CLI) or skip writing (API) to avoid conflicts.
+- Ask before running destructive seed SQL (`DROP`, `TRUNCATE`, mass `DELETE`).
+- For production workloads, recommend standard Neon provisioning instead of temporary claimable databases.
+- If users need long-term persistence, instruct them to open the claim URL right away.
+- After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify `.gitignore` without confirmation.
+
 ## REST API
 
 **Base URL:** `https://neon.new/api/v1`
@@ -148,43 +208,6 @@ Returns `databaseUrl` (pooled), `databaseUrlDirect` (direct, for migrations), `c
 
 For Vite projects, `vite-plugin-neon-new` auto-provisions a database on `vite dev` if `DATABASE_URL` is missing. Install with `npm install -D vite-plugin-neon-new`. See the [Claimable Postgres docs](https://neon.com/docs/reference/claimable-postgres#vite-plugin) for configuration.
 
-## Agent Workflow
-
-### API path
-
-1. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
-2. **Provision:** POST to `https://neon.new/api/v1/database` with `{"ref": "agent-skills"}`.
-3. **Parse response:** Extract `connection_string`, `claim_url`, and `expires_at` from the JSON response.
-4. **Write .env:** Write `DATABASE_URL=<connection_string>` to the project's `.env` (or the user's preferred file and key). Do not overwrite an existing key without confirmation.
-5. **Seed (if needed):** If the user has a seed SQL file, run it against the new database:
-   ```bash
-   psql "$DATABASE_URL" -f seed.sql
-   ```
-6. **Report:** Tell the user where the connection string was written, which key was used, and share the claim URL. Remind them: the database works now; claim within 72 hours to keep it permanently.
-7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`).
-
-### CLI path
-
-1. **Check .env:** Check the target `.env` for an existing `DATABASE_URL` (or chosen key). If present, do not run. Offer remove, `--env`, or `--key` and get confirmation.
-2. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
-3. **Gather options:** Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication).
-4. **Run:** Execute with `@latest --yes` plus the confirmed options. Always use `@latest` to avoid stale cached versions. `--yes` skips interactive prompts that would stall the agent.
-   ```bash
-   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
-   ```
-5. **Verify:** Confirm the connection string was written to the intended file.
-6. **Report:** Tell the user where the connection string was written, which key was used, and that a claim URL is in the env file. Remind them: the database works now; claim within 72 hours to keep it permanently.
-7. **Optional:** Offer a quick connection test (e.g. `SELECT 1`).
-
-### Output Checklist
-
-Always report:
-
-- Where the connection string was written (e.g. `.env`)
-- Which variable key was used (`DATABASE_URL` or custom key)
-- The claim URL (from `.env` or API response)
-- That unclaimed databases are temporary (72 hours)
-
 ## Claiming
 
 Claiming is optional. The database works immediately without it. To optionally claim, the user opens the claim URL in a browser, where they sign in or create a Neon account to claim the database.
@@ -235,15 +258,3 @@ Region cannot be changed for claimable databases. Unclaimed databases have stric
 | Transfer   | 1 GB      | ~5 GB               |
 | Branches   | No        | Yes                 |
 | Expiration | 72 hours  | None                |
-
-## Auto-provisioning
-
-If the agent needs a database to fulfill a task (e.g. "build me a todo app with a real database") and the user has not provided a connection string, provision one via the API and inform the user. Include the claim URL so they can keep it.
-
-## Safety and UX Notes
-
-- Do not overwrite existing env vars. Check first, then use `--env` or `--key` (CLI) or skip writing (API) to avoid conflicts.
-- Ask before running destructive seed SQL (`DROP`, `TRUNCATE`, mass `DELETE`).
-- For production workloads, recommend standard Neon provisioning instead of temporary claimable databases.
-- If users need long-term persistence, instruct them to open the claim URL right away.
-- After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify `.gitignore` without confirmation.

package/dist/global-skills/design-my-data/SKILL.md

@@ -30,6 +30,8 @@ translate every error · celebrate. You do all the planning; the builder describ
    **Verify:** builder says yes.
 
 4. **Route to save-data.** Hand off to `save-data.md` to provision the database, wire CRUD, and test.
+   When `DATA_PROVIDER=supabase`, pick an RLS preset from `infra/supabase/policies/` (user-owned,
+   team-owned, or public-read) and include it in the migration — see `harden.md` step on database rules.
    **Verify:** `save-data` definition of done.
 
 ## When to skip

package/dist/global-skills/eas-app-stores/SKILL.md

@@ -150,3 +150,11 @@ eas build:view
 # View submission status
 eas submit:list
 ```
+
+## 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-app-stores" "<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-app-stores/references/play-store.md

@@ -6,6 +6,8 @@
 2. **App Created in Console** - Create your app listing before first submission
 3. **Service Account** - For automated submissions via EAS
 
+Once these are complete, the default `eas submit` works for a first-time submission and creates the app's first release on the internal testing track. Store listing, content rating, and pricing are only required before promoting a release to production.
+
 ## Service Account Setup
 
 ### 1. Create Service Account

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

@@ -421,3 +421,11 @@ export async function GET(request: Request) {
 - Keep API routes focused — one responsibility per endpoint
 - Use TypeScript for type safety
 - Log errors server-side for debugging
+
+## 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-hosting" "<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-observe/SKILL.md

@@ -1,32 +1,54 @@
 ---
 name: eas-observe
-description: EAS service (paid). Use for anything related to EAS Observe - adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive, the useObserve hook, the Expo Router / React Navigation integrations for per-route metrics, and user-defined events via `Observe.logEvent`), querying via the EAS CLI (`eas observe:metrics-summary`, `observe:metrics`, `observe:routes`, `observe:events`, `observe:versions`), or interpreting the resulting metrics (cold/warm launch, TTR, TTI, navigation cold/warm TTR, update download, and the TTI frameRate params for triaging slow startups).
-version: 1.0.0
+description: EAS service (paid). Use for anything related to EAS Observe - adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive and ObserveInteractiveMarker, the useObserve hook, the Expo Router / React Navigation integrations for per-route metrics, user-defined events via `Observe.logEvent`, error reporting via ObserveErrorBoundary and `Observe.reportError`, and runtime config such as sampleRate and dispatchInDebug), querying via the EAS CLI (`eas observe:metrics-summary`, `observe:metrics`, `observe:routes`, `observe:events`, `observe:session`, `observe:versions`), interpreting the resulting metrics (cold/warm launch, TTR, TTI, navigation cold/warm TTR, update download, and the TTI frameRate/device/network params for triaging slow startups), or shipping an Observe integration inside a third-party package.
+version: 1.1.0
 license: MIT
 ---
 
 # EAS Observe
 
-> **EAS service - costs apply.** EAS Observe is a paid Expo Application Services product with free-tier limits. Ingesting and querying production metrics counts against your plan's event/usage allowance. Review https://expo.dev/pricing before enabling it in production.
+> **EAS service - costs apply.** EAS Observe is an Expo Application Services product. The free EAS plan allows up to 10,000 monthly active users, with a limited set of features; higher usage requires a paid subscription. For details, see https://expo.dev/pricing#plan-features.
 
-EAS Observe tracks startup, navigation, and custom-event performance from production Expo apps.
+EAS Observe tracks startup, navigation, and custom-event performance from production Expo apps. It needs a development or production build — the native library is not in Expo Go.
 
 > **Source of truth:** https://docs.expo.dev/eas/observe/ — always consult the canonical docs when API details matter, especially get-started, configuration, integrations, and the metrics reference. EAS Observe is evolving; this skill's references are written to stay accurate but may lag the docs.
 
 ## Which reference to read
 
-The three reference files in `./references/` cover the three things people typically need this skill for:
+The four reference files in `./references/` cover what people typically need this skill for:
 
-- **Adding EAS Observe to a project** → [`./references/setup.md`](./references/setup.md). Install, wrap the root layout (`AppMetricsRoot` on SDK 55, `ObserveRoot` on SDK 56+), call `markInteractive()` (global on SDK 55, via the `useObserve()` hook on SDK 56+), optional per-route navigation metrics through the Expo Router / React Navigation integrations, and user-defined events via `Observe.logEvent` (SDK 56+).
-- **Querying metrics from the terminal** → [`./references/queries.md`](./references/queries.md). The five `eas observe:*` commands — `metrics-summary`, `metrics`, `routes`, `events`, `versions` — with flags, table layouts, JSON shapes, and common workflows.
-- **Reading a dashboard or CLI output** → [`./references/metrics.md`](./references/metrics.md). Target thresholds per metric, what the TTI `frameRate.*` params mean, and diagnostic patterns for telling slow-but-smooth startup apart from main-thread contention or hard blocks.
+- **Adding EAS Observe to a project** → [`./references/setup.md`](./references/setup.md). Install, wrap the root layout (`AppMetricsRoot` on SDK 55, `ObserveRoot` on SDK 56+), mark the app interactive (global `markInteractive()` on SDK 55, the `useObserve()` hook or `<ObserveInteractiveMarker />` on SDK 56+), optional per-route navigation metrics through the Expo Router / React Navigation integrations, user-defined events via `Observe.logEvent` (SDK 56+), error reporting, and runtime configuration (sampling, dispatch, environments, custom endpoint).
+- **Querying metrics from the terminal** → [`./references/queries.md`](./references/queries.md). The six `eas observe:*` commands — `metrics-summary`, `metrics`, `routes`, `events`, `session`, `versions` — with flags, metric aliases, table layouts, JSON shapes, and common workflows.
+- **Reading a dashboard or CLI output** → [`./references/metrics.md`](./references/metrics.md). Target thresholds per metric, what the automatic TTI params mean (`frameRate.*`, `device.*`, `network.*`), and diagnostic patterns for telling slow-but-smooth startup apart from main-thread contention, hard blocks, or throttled devices.
+- **Shipping an Observe integration in a library** → [`./references/third-party.md`](./references/third-party.md). For package authors only (SDK 57+): optional peer dependency, config declaration merging, `Observe.registerIntegration()`, and event naming.
 
 ## Quick links to the docs
 
 - Get started: https://docs.expo.dev/eas/observe/get-started/
 - Dashboard guide: https://docs.expo.dev/eas/observe/dashboard/
+- Querying with EAS CLI: https://docs.expo.dev/eas/observe/eas-cli/
 - Metrics reference: https://docs.expo.dev/eas/observe/reference/metrics/
 - Expo Router integration: https://docs.expo.dev/eas/observe/integrations/expo-router/
 - React Navigation integration: https://docs.expo.dev/eas/observe/integrations/react-navigation/
 - User-defined events: https://docs.expo.dev/eas/observe/events/
 - Configuration: https://docs.expo.dev/eas/observe/configuration/
+- Third-party integrations: https://docs.expo.dev/eas/observe/integrations/third-party/
+- EAS Update download performance: https://docs.expo.dev/eas/observe/eas-update/
+- Troubleshooting: https://docs.expo.dev/eas/observe/reference/troubleshooting/
+
+## Known gaps between the docs and the shipped code
+
+Verified against `eas-cli` 21.8.0 and `expo-observe` 57.0.9. Trust this skill's references over the docs on these points, but re-check with `--help` and the installed package before relying on them:
+
+- All six CLI commands are on the [Querying with EAS CLI](https://docs.expo.dev/eas/observe/eas-cli/) page. Older doc builds list only four and omit `observe:routes` and `observe:session`.
+- Navigation metric aliases are `nav_cold_ttr`, `nav_warm_ttr`, and `nav_tti`. There are no bare `cold_ttr` / `warm_ttr` aliases in the CLI.
+- Sorting uses `--sort <slowest|fastest|newest|oldest>`. There is no `--order` flag.
+- `ObserveErrorBoundary`, `Observe.reportError`, and `configure({ errorHandlingEnabled })` are exported but undocumented. Observe still has no crash reporting; use Sentry or BugSnag for that.
+
+## 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-observe" "<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-observe/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "EAS Observe"
   short_description: "Paid EAS service. Set up expo-observe app metrics and query launch, route, event, and version performance with the EAS CLI"
-  default_prompt: "Use $eas-observe to add expo-observe instrumentation (AppMetricsRoot/ObserveRoot, useObserve, the router integrations), query metrics with eas observe:* commands, and interpret cold/warm launch, TTR, and TTI results."
+  default_prompt: "Use $eas-observe to add expo-observe instrumentation (AppMetricsRoot/ObserveRoot, useObserve, ObserveInteractiveMarker, the router integrations, error reporting), query metrics with eas observe:* commands, and interpret cold/warm launch, TTR, and TTI results."

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

@@ -4,7 +4,7 @@ Quick reference for reading EAS Observe dashboards and CLI output.
 
 > Source: https://docs.expo.dev/eas/observe/reference/metrics/ — this is the canonical reference for metrics. Consult this page for the latest guidance, full prose definitions, optimization tips, and rationale.
 
-All durations are in seconds. Data is retained for 90 days. All durations are in seconds. By default, every installation dispatches all of its events. Apps with high volumes can opt into per-installation sampling via configure({ sampleRate }). See [Sampling](https://docs.expo.dev/eas/observe/configuration/#sampling).
+All durations are in seconds. Metric data is retained for a minimum of 60 days. By default, every installation dispatches all of its events; high-volume apps can sample per installation with `configure({ sampleRate })` — see [Sampling](https://docs.expo.dev/eas/observe/configuration/#sampling).
 
 ## Target thresholds
 
@@ -18,9 +18,11 @@ All durations are in seconds. Data is retained for 90 days. All durations are in
 
 Both TTR and TTI are measured *from native launch* through the React render, so the cold-launch portion counts against them.
 
-## Interpreting TTI events (frameRate params)
+## Interpreting TTI events (automatic params)
 
-Every TTI event carries three frame-rate params. The pattern of high/low values across them tells you *what kind* of slowness you're seeing.
+Every TTI event carries automatic params in three groups: frame rate, device state, and network state. Read the frame-rate group to classify *what kind* of slowness you're seeing, then read the device and network groups to decide whether the cause is the code or the conditions.
+
+### Frame rate — what kind of slowness
 
 | Param | Definition | What it indicates |
 |---|---|---|
@@ -34,6 +36,55 @@ Every TTI event carries three frame-rate params. The pattern of high/low values
 - **High TTI + high totalDelay + many slowFrames** → main-thread contention. Offload work, simplify the initial render tree.
 - **High TTI + high totalDelay + any frozenFrames** → something is blocking hard. Look for synchronous I/O, large JSON parsing, or blocking network calls.
 
+### Device state — is the regression environmental?
+
+| Param | Type | What it indicates |
+|---|---|---|
+| `expo.device.lowPowerMode` | boolean | OS power saver was active (Low Power Mode on iOS, Battery Saver on Android). It throttles CPU, GPU, and background work. A regression that disappears when you filter this out is environmental, not a code change. |
+| `expo.device.thermalState` | `nominal` \| `fair` \| `serious` \| `critical` \| `unknown` | Sustained `serious`/`critical` means the OS is throttling. Startup slows independently of any app change. |
+| `expo.device.batteryLevel` | number, 0–1 | Fractional charge at TTI. Rules out throttling on devices that manage performance aggressively at low charge. Omitted when the OS reports no value. |
+| `expo.device.batteryCharging` | boolean | Charging raises sustained CPU ceilings on iOS and some Android OEMs. Non-charging samples are the more conservative population. |
+
+### Network state — is startup network-bound?
+
+| Param | Type | What it indicates |
+|---|---|---|
+| `expo.network.connected` | boolean | If TTI degrades only when `true`, startup is network-bound. If it degrades when `false`, the app does too much before showing cached content. |
+| `expo.network.type` | `wifi` \| `cellular` \| `ethernet` \| `none` \| `other` \| `unknown` | Compare cellular against Wi-Fi. A large gap points to network-bound startup work. VPN traffic reports the underlying transport. The value set is identical on both platforms, so dashboards need no per-platform branching. |
+| `expo.network.isExpensive` | boolean | Both platforms. The OS considers the connection metered (cellular, hotspot). Present only when a network exists. |
+| `expo.network.isConstrained` | boolean | **iOS only.** Low Data Mode is on for this path, so the system defers background transfers. |
+| `expo.network.dataSaverEnabled` | boolean | **Android only.** Data Saver is on. It is the nearest equivalent of Low Data Mode, but process-wide rather than per-path, hence the separate key. |
+
+### Network requests — was the network the cause?
+
+TTI events summarize the HTTP requests made during launch, from the end of the native launch to the `markInteractive()` call. Traffic is observed automatically — `URLSession` on iOS, `OkHttpClient` on Android, which covers `fetch` — and Observe's own uploads are excluded. All of these are omitted when the window held no requests.
+
+| Param | Unit | What it indicates |
+|---|---|---|
+| `expo.network.requests.count` | count | Requests that finished in the window. A request still in flight when the app became interactive is not counted anywhere in this table. |
+| `expo.network.requests.failed` | count | Errored, returned 4xx/5xx, never got a response, or broke partway through the body. Redirects are not failures. |
+| `expo.network.requests.bytesReceived` / `.bytesSent` | bytes | On-the-wire totals for the window. |
+| `expo.network.requests.totalDuration` | seconds | Sum of every request duration, failures included. Exceeds wall-clock when requests overlap; one timeout contributes the client's full timeout interval. |
+| `expo.network.requests.throughputBytesPerSecond` | bytes/sec | Received bytes over the time bytes were actually moving (union of transfer windows, measured from each first byte). Excludes DNS, connect, server think time, cache hits, and failures. Requests the OS did not clearly identify as network loads are excluded too. Omitted when nothing was received. |
+| `expo.network.requests.slowest.duration` | seconds | The single longest **completed** request. Requests that never produced a response are excluded, since a timeout measures the client's own setting. |
+| `expo.network.requests.slowest.host` | string | Host of that request. |
+| `expo.network.requests.slowest.statusCode` | number | Explains an empty response: `bytesReceived` of 0 is routine on a 304, a problem on a 200. |
+| `expo.network.requests.slowest.timeToFirstByte` | seconds | Includes server processing, so treat it as a proxy for network quality, not a measurement of it. |
+| `expo.network.requests.slowest.bytesReceived` | bytes | Separates "slow because it moved a lot of data" from "slow while idle". |
+
+**Diagnostic patterns:**
+
+- **`slowest.duration` mostly `timeToFirstByte`** → the server was slow to answer. Optimize the endpoint, or stop blocking startup on it.
+- **Small `timeToFirstByte` + large `bytesReceived`** → the transfer itself was slow. Shrink the payload or defer it.
+- **High `failed` + high `totalDuration`** → the launch burned time on requests that never arrived. Add timeouts and render cached content first.
+- **Low `throughputBytesPerSecond` on `wifi`** → suspect the population, not the code; cross-check `isExpensive` and `isConstrained` / `dataSaverEnabled`.
+
+> The summary is bounded by an in-memory ring buffer of the 200 most recent requests. A launch that makes more undercounts, so read these as a sample of a very busy window.
+
+### Custom params
+
+You can attach your own params to the TTI event, and override the route name it is tagged with. See [`./setup.md`](./setup.md) for the call syntax.
+
 ## Dispatch caveats
 
 - **Debug builds** (native debug OR JS bundle with `__DEV__` = true) do **not** dispatch metrics unless `configure({ dispatchInDebug: true })` is set.

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

@@ -1,34 +1,40 @@
 # EAS Observe CLI
 
-EAS Observe collects app performance telemetry and custom events from Expo apps and exposes them through five EAS CLI commands. Pass the `--help` flag to any command for the latest API.
+EAS Observe collects app performance telemetry and custom events from Expo apps and exposes them through six EAS CLI commands. Pass the `--help` flag to any command for the latest API — the flags below were verified against `eas-cli` 21.8.0.
+
+> Source: https://docs.expo.dev/eas/observe/eas-cli/ — the canonical CLI page. This reference adds table layouts, JSON output shapes, and pagination details that the docs page does not cover.
 
 ## Commands Overview
 
 | Command | Purpose |
 |---------|---------|
-| `eas observe:metrics-summary` | Per-version statistical aggregates for app-startup performance metrics (median, p90, etc.) |
-| `eas observe:metrics` | Individual performance metric samples ordered by value or timestamp (paginated) |
-| `eas observe:routes` | Per-route statistical aggregates for navigation metrics (Cold TTR, Warm TTR, Nav TTI) |
+| `eas observe:metrics-summary` | Per-version statistical aggregates for startup and navigation metrics (median, p90, etc.) |
+| `eas observe:metrics` | Individual metric samples ordered by value or timestamp (paginated) |
+| `eas observe:routes` | Per-route statistical aggregates for navigation metrics (Nav Cold TTR, Nav Warm TTR, Nav TTI) |
 | `eas observe:events` | Custom events emitted by the app via `logEvent` — name summary, all events, or filtered by event name (paginated) |
+| `eas observe:session` | Full timeline of metric and log events for one session |
 | `eas observe:versions` | App version hierarchy with build numbers, OTA update IDs, and event counts |
 
-All five commands share these common flags:
+> Older published docs list only `metrics-summary`, `metrics`, `events`, and `versions`. All six are on the [Querying with EAS CLI](https://docs.expo.dev/eas/observe/eas-cli/) page; run `--help` to confirm them on your installed version.
+
+All six commands share these flags:
 
-- `--platform ios` or `--platform android` — filter by platform (default: both)
 - `--start <ISO date>` and `--end <ISO date>` — explicit time range
-- `--days <N>` — show data from the last N days (mutually exclusive with `--start`/`--end`)
+- `--days <N>` — show data from the last N days (mutually exclusive with `--start`/`--end`, minimum 1)
 - `--project-id <id>` — run against a specific project without needing a project directory. When passed, the command will not try to create a new EAS project where one is unneeded.
 - `--json` — machine-readable output (implies `--non-interactive`)
 - `--non-interactive` — fail instead of prompting
 
+`--platform ios` / `--platform android` (default: both) is on every command **except `observe:session`**, which is scoped to one session already.
+
 Default time range is the last 60 days when none of `--days`, `--start`, `--end` is given.
 
+**Plan gating.** Observe is a paid feature, and the server rejects queries the account's plan does not include (`EAS_OBSERVE_PLAN_UPGRADE_REQUIRED` or `EAS_OBSERVE_FEATURE_NOT_AVAILABLE_IN_FREE_TIER`). The CLI surfaces the server's upgrade message, which links to the account's billing page. Session timelines in particular are checked before the interactive picker runs. A plan-gate failure is not a bug in the command or its flags.
+
 ## Supported Metrics
 
 ### App-startup metrics
 
-Used by `observe:metrics-summary` and `observe:metrics`.
-
 | Alias | Full name | Display |
 |-------|-----------|---------|
 | `tti` | `expo.app_startup.tti` | Startup TTI (time to interactive) |
@@ -40,14 +46,18 @@ Used by `observe:metrics-summary` and `observe:metrics`.
 
 ### Navigation metrics
 
-Used by `observe:routes`. Measured per route name.
+Emitted only when a navigation integration is enabled (SDK 56+). Measured per route name.
 
 | Alias | Full name | Display |
 |-------|-----------|---------|
-| `cold_ttr` | `expo.navigation.cold_ttr` | Nav Cold TTR |
-| `warm_ttr` | `expo.navigation.warm_ttr` | Nav Warm TTR |
+| `nav_cold_ttr` | `expo.navigation.cold_ttr` | Nav Cold TTR |
+| `nav_warm_ttr` | `expo.navigation.warm_ttr` | Nav Warm TTR |
 | `nav_tti` | `expo.navigation.tti` | Nav TTI |
 
+**Which command takes which alias.** `observe:metrics` (positional argument) and `observe:metrics-summary --metric` accept **all nine** aliases — startup and navigation. `observe:routes --metric` accepts only the three navigation aliases. Use the `nav_` prefix everywhere; there are no bare `cold_ttr` / `warm_ttr` aliases.
+
+`observe:metrics` also accepts a full metric name in place of an alias, for example `eas observe:metrics expo.app_startup.tti`. `observe:routes` accepts full navigation names the same way. The `--metric` flags on `metrics-summary` and `routes` are strict oclif options, so they take aliases only.
+
 ## `eas observe:metrics-summary`
 
 Shows per-version statistical aggregates for one or more metrics, with separate tables per platform.
@@ -62,6 +72,9 @@ eas observe:metrics-summary --metric tti
 # Multiple metrics — each renders as its own table
 eas observe:metrics-summary --metric tti --metric cold_launch
 
+# Navigation metrics aggregate per version here, per route in observe:routes
+eas observe:metrics-summary --metric nav_tti
+
 # Choose which statistics to display
 eas observe:metrics-summary --metric tti --stat median --stat p90 --stat eventCount
 
@@ -69,9 +82,11 @@ eas observe:metrics-summary --metric tti --stat median --stat p90 --stat eventCo
 eas observe:metrics-summary --metric tti --days 14 --platform ios
 ```
 
-**Stat flags:** `min`, `max`, `median` (alias `med`), `average` (alias `avg`), `p80`, `p90`, `p99`, `eventCount` (alias `count`).
+**Stat flags:** exactly `min`, `median`, `max`, `average`, `p80`, `p90`, `p99`, `eventCount`. This command takes **no aliases** — `med`, `avg`, and `count` are rejected here (they work only on `observe:routes`).
 
-**Default stats:** `median` + `eventCount` in the table; all stats in JSON.
+**Default stats:** `median` + `eventCount` in the table; all eight in JSON.
+
+This command has no `--limit`, `--after`, `--app-version`, or `--update-id`. It always aggregates every version in the time range.
 
 **Table layout:**
 - One table per metric (with merged value + event count cells, e.g. `0.45s (150)`)
@@ -111,6 +126,9 @@ eas observe:metrics
 # Specify metric as positional arg
 eas observe:metrics tti
 
+# Navigation metrics work here too
+eas observe:metrics nav_tti --sort slowest
+
 # Filter by version or update, sort by slowest
 eas observe:metrics tti --app-version 1.2.0 --sort slowest --limit 20
 
@@ -143,7 +161,7 @@ eas observe:routes
 eas observe:routes --metric nav_tti --days 7 --platform ios
 
 # Multiple metrics and stats
-eas observe:routes --metric cold_ttr --metric warm_ttr --stat median --stat p90 --stat count
+eas observe:routes --metric nav_cold_ttr --metric nav_warm_ttr --stat median --stat p90 --stat count
 
 # Filter to a single build
 eas observe:routes --app-version 1.2.0 --build-number 42
@@ -156,7 +174,7 @@ eas observe:routes --after <cursor>
 ```
 
 **Routes-specific flags:**
-- `--metric <cold_ttr|warm_ttr|nav_tti>` — navigation metric(s) to display, can be repeated. Defaults to all three.
+- `--metric <nav_cold_ttr|nav_warm_ttr|nav_tti>` — navigation metric(s) to display, can be repeated. Defaults to all three.
 - `--stat <median|p90|count>` — statistic(s) per metric. Aliases: `med` → `median`, `event_count` / `eventCount` → `count`.
 - `--limit <N>` — routes per page (default **50**, max **200**, different from `metrics`/`events` which default to 10).
 - `--after <cursor>` — pagination cursor from the previous run.
@@ -222,7 +240,7 @@ eas observe:events login_failed --after <cursor>
 
 **Events-specific flags:**
 - `--all-events` — when no event name argument is given, list all events instead of the name summary. Cannot be combined with an event name argument.
-- `--session-id <id>` — filter to events from a single session (events-only)
+- `--session-id <id>` — filter to events from a single session (events-only). With no event name argument, this lists the session's events instead of the event-name summary. For the full timeline — metrics as well as log events — use `observe:session`.
 - `--app-version <version>` — filter by app version string
 - `--update-id <id>` — filter by EAS update ID
 - `--limit <N>` — events per page (default 10, max 100)
@@ -267,6 +285,43 @@ eas observe:events login_failed --after <cursor>
 
 The name-summary mode returns `{ "names": [{ "eventName": "...", "count": 123 }], "isTruncated": false }`.
 
+## `eas observe:session`
+
+Shows the full timeline of metric and log events for a single session — the CLI equivalent of the dashboard's session view. Use it after `observe:metrics` surfaces a slow sample: take that sample's `sessionId` (present in `--json` output) and replay everything that session recorded.
+
+```bash
+# Interactive: pick a metric, then pick a session from the candidate list
+eas observe:session
+
+# Inspect a known session
+eas observe:session <session-id>
+
+# Pick a session from the slowest TTI events in the last 7 days
+eas observe:session --event-name tti --sort slowest --days 7
+```
+
+**Session-specific flags:**
+- `[SESSIONID]` — positional. Omit it in interactive mode to choose from a list. **Required in non-interactive mode**, including under `--json`.
+- `--event-name <name>` — metric or log event used to build the candidate session list (for example `tti`, `cold_launch`, `login_pressed`). Prompts when omitted in interactive mode.
+- `--sort <slowest|fastest|newest|oldest>` — orders the candidate events. Prompts when omitted in interactive mode. No default, unlike `observe:metrics`.
+
+**The picker flags and the session ID are mutually exclusive.** `--event-name`, `--sort`, `--days`, `--start`, and `--end` describe how to *find* a session, so passing any of them together with a session ID throws. Query a known session with the ID alone.
+
+This command has no `--platform`, `--limit`, or `--after` flag. It takes the shared time-range, `--project-id`, `--json`, and `--non-interactive` flags.
+
+**JSON output shape:**
+```json
+{
+  "sessionId": "...",
+  "metadata": { "...": "..." },
+  "entries": [{ "...": "..." }],
+  "hasMoreMetricEvents": false,
+  "hasMoreLogEvents": false
+}
+```
+
+`entries` interleaves metric and log events for the session. The two `hasMore*` flags report truncation per event kind; there is no cursor to page with.
+
 ## `eas observe:versions`
 
 Shows app version hierarchy with build numbers, OTA update IDs, and event counts per version.
@@ -305,6 +360,12 @@ eas observe:metrics-summary --metric update_download --days 7
 eas observe:routes --metric nav_tti --stat median --stat p90 --days 7
 ```
 
+**"What happened during that one slow session?"**
+```bash
+eas observe:metrics tti --sort slowest --days 7 --json   # read sessionId from a sample
+eas observe:session <session-id>
+```
+
 **"How does navigation perform on just the routes I care about?"**
 ```bash
 eas observe:routes --route-name /home --route-name /checkout --days 7