novahiz 0.1.0

package/bundled-skills/eas-hosting/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: eas-hosting
+description: EAS service (paid). Deploy Expo websites and Expo Router API routes to EAS Hosting - export the web bundle, run eas deploy for production and PR preview URLs, manage environment secrets and custom domains, and work within the Cloudflare Workers runtime. Also covers authoring API routes (+api.ts handlers, HTTP methods, request handling, CORS). Use when deploying an Expo web app or API routes, setting up EAS Hosting, or configuring hosting environments and domains. Not for native builds or store releases - use the eas-app-stores skill for those.
+version: 1.0.0
+license: MIT
+---
+
+# EAS Hosting
+
+> **EAS service - costs apply.** EAS Hosting is a paid Expo Application Services product with free-tier limits; production deploys use your plan's request and bandwidth allowance. See https://expo.dev/pricing. Authoring API routes and exporting the web bundle are free and open source, and you can self-host the exported server output instead of EAS Hosting.
+
+EAS Hosting deploys your Expo **web app and API routes** to Expo's managed edge (Cloudflare Workers). Export the web bundle with `npx expo export -p web` and ship it with `eas deploy` - the same command deploys any Expo Router API routes bundled alongside it. This skill covers deploying a website, authoring API routes, and the hosting runtime; see the Deployment section below for the deploy workflow.
+
+## When to Use API Routes
+
+Use API routes when you need:
+
+- **Server-side secrets** — API keys, database credentials, or tokens that must never reach the client
+- **Database operations** — Direct database queries that shouldn't be exposed
+- **Third-party API proxies** — Hide API keys when calling external services (OpenAI, Stripe, etc.)
+- **Server-side validation** — Validate data before database writes
+- **Webhook endpoints** — Receive callbacks from services like Stripe or GitHub
+- **Rate limiting** — Control access at the server level
+- **Heavy computation** — Offload processing that would be slow on mobile
+
+## When NOT to Use API Routes
+
+Avoid API routes when:
+
+- **Data is already public** — Use direct fetch to public APIs instead
+- **No secrets required** — Static data or client-safe operations
+- **Real-time updates needed** — Use WebSockets or services like Supabase Realtime
+- **Simple CRUD** — Consider Firebase, Supabase, or Convex for managed backends
+- **File uploads** — Use direct-to-storage uploads (S3 presigned URLs, Cloudflare R2)
+- **Authentication only** — Use Clerk, Auth0, or Firebase Auth instead
+
+## File Structure
+
+API routes live in the `app` directory with `+api.ts` suffix:
+
+```
+app/
+  api/
+    hello+api.ts          → GET /api/hello
+    users+api.ts          → /api/users
+    users/[id]+api.ts     → /api/users/:id
+  (tabs)/
+    index.tsx
+```
+
+## Basic API Route
+
+```ts
+// app/api/hello+api.ts
+export function GET(request: Request) {
+  return Response.json({ message: "Hello from Expo!" });
+}
+```
+
+## HTTP Methods
+
+Export named functions for each HTTP method:
+
+```ts
+// app/api/items+api.ts
+export function GET(request: Request) {
+  return Response.json({ items: [] });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  return Response.json({ created: body }, { status: 201 });
+}
+
+export async function PUT(request: Request) {
+  const body = await request.json();
+  return Response.json({ updated: body });
+}
+
+export async function DELETE(request: Request) {
+  return new Response(null, { status: 204 });
+}
+```
+
+## Dynamic Routes
+
+```ts
+// app/api/users/[id]+api.ts
+export function GET(request: Request, { id }: { id: string }) {
+  return Response.json({ userId: id });
+}
+```
+
+## Request Handling
+
+### Query Parameters
+
+```ts
+export function GET(request: Request) {
+  const url = new URL(request.url);
+  const page = url.searchParams.get("page") ?? "1";
+  const limit = url.searchParams.get("limit") ?? "10";
+
+  return Response.json({ page, limit });
+}
+```
+
+### Headers
+
+```ts
+export function GET(request: Request) {
+  const auth = request.headers.get("Authorization");
+
+  if (!auth) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  return Response.json({ authenticated: true });
+}
+```
+
+### JSON Body
+
+```ts
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+
+  if (!email || !password) {
+    return Response.json({ error: "Missing fields" }, { status: 400 });
+  }
+
+  return Response.json({ success: true });
+}
+```
+
+## Environment Variables
+
+Use `process.env` for server-side secrets:
+
+```ts
+// app/api/ai+api.ts
+export async function POST(request: Request) {
+  const { prompt } = await request.json();
+
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: "gpt-4",
+      messages: [{ role: "user", content: prompt }],
+    }),
+  });
+
+  const data = await response.json();
+  return Response.json(data);
+}
+```
+
+Set environment variables:
+
+- **Local**: Create `.env` file (never commit)
+- **EAS Hosting**: Use `eas env:create` or Expo dashboard
+
+## CORS Headers
+
+Add CORS for web clients:
+
+```ts
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization",
+};
+
+export function OPTIONS() {
+  return new Response(null, { headers: corsHeaders });
+}
+
+export function GET() {
+  return Response.json({ data: "value" }, { headers: corsHeaders });
+}
+```
+
+## Error Handling
+
+```ts
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    // Process...
+    return Response.json({ success: true });
+  } catch (error) {
+    console.error("API error:", error);
+    return Response.json({ error: "Internal server error" }, { status: 500 });
+  }
+}
+```
+
+## Testing Locally
+
+Start the development server with API routes:
+
+```bash
+npx expo serve
+```
+
+This starts a local server at `http://localhost:8081` with full API route support.
+
+Test with curl:
+
+```bash
+curl http://localhost:8081/api/hello
+curl -X POST http://localhost:8081/api/users -H "Content-Type: application/json" -d '{"name":"Test"}'
+```
+
+## Deployment to EAS Hosting
+
+### Prerequisites
+
+```bash
+npm install -g eas-cli
+eas login
+```
+
+### Deploy
+
+Deploying ships your web bundle and any Expo Router API routes together - `eas deploy` handles both. The export runs whether you have a full website, an API-routes-only backend, or both.
+
+```bash
+# Export the web bundle (includes any API routes)
+npx expo export -p web
+
+# Deploy a preview (PR-style URL)
+npx eas-cli@latest deploy
+
+# Deploy to production
+npx eas-cli@latest deploy --prod
+```
+
+Everything lands on EAS Hosting (Cloudflare Workers).
+
+### Environment Variables for Production
+
+```bash
+# Create a secret
+eas env:create --name OPENAI_API_KEY --value sk-xxx --environment production
+
+# Or use the Expo dashboard
+```
+
+### Custom Domain
+
+Configure in `eas.json` or Expo dashboard.
+
+### Automate with EAS Workflows
+
+Deploy the website (and API routes) on every push to main with a `type: deploy` workflow:
+
+`.eas/workflows/deploy.yml`
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+# https://docs.expo.dev/eas/workflows/syntax/#deploy
+jobs:
+  deploy_web:
+    type: deploy
+    params:
+      prod: true
+```
+
+Preview deploys for pull requests use the same job type with `prod: false`:
+
+```yaml
+name: Web PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  preview:
+    type: deploy
+    params:
+      prod: false
+```
+
+To author or validate workflow YAML beyond these examples, use the `eas-workflows` skill.
+
+## EAS Hosting Runtime (Cloudflare Workers)
+
+API routes run on Cloudflare Workers. Key limitations:
+
+### Missing/Limited APIs
+
+- **No Node.js filesystem** — `fs` module unavailable
+- **No native Node modules** — Use Web APIs or polyfills
+- **Limited execution time** — 30 second timeout for CPU-intensive tasks
+- **No persistent connections** — WebSockets require Durable Objects
+- **fetch is available** — Use standard fetch for HTTP requests
+
+### Use Web APIs Instead
+
+```ts
+// Use Web Crypto instead of Node crypto
+const hash = await crypto.subtle.digest(
+  "SHA-256",
+  new TextEncoder().encode("data")
+);
+
+// Use fetch instead of node-fetch
+const response = await fetch("https://api.example.com");
+
+// Use Response/Request (already available)
+return new Response(JSON.stringify(data), {
+  headers: { "Content-Type": "application/json" },
+});
+```
+
+### Database Options
+
+Since filesystem is unavailable, use cloud databases:
+
+- **Cloudflare D1** — SQLite at the edge
+- **Turso** — Distributed SQLite
+- **PlanetScale** — Serverless MySQL
+- **Supabase** — Postgres with REST API
+- **Neon** — Serverless Postgres
+
+Example with Turso:
+
+```ts
+// app/api/users+api.ts
+import { createClient } from "@libsql/client/web";
+
+const db = createClient({
+  url: process.env.TURSO_URL!,
+  authToken: process.env.TURSO_AUTH_TOKEN!,
+});
+
+export async function GET() {
+  const result = await db.execute("SELECT * FROM users");
+  return Response.json(result.rows);
+}
+```
+
+## Calling API Routes from Client
+
+```ts
+// From React Native components
+const response = await fetch("/api/hello");
+const data = await response.json();
+
+// With body
+const response = await fetch("/api/users", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "John" }),
+});
+```
+
+## Common Patterns
+
+### Authentication Middleware
+
+```ts
+// utils/auth.ts
+export async function requireAuth(request: Request) {
+  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+
+  if (!token) {
+    throw new Response(JSON.stringify({ error: "Unauthorized" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  // Verify token...
+  return { userId: "123" };
+}
+
+// app/api/protected+api.ts
+import { requireAuth } from "../../utils/auth";
+
+export async function GET(request: Request) {
+  const { userId } = await requireAuth(request);
+  return Response.json({ userId });
+}
+```
+
+### Proxy External API
+
+```ts
+// app/api/weather+api.ts
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const city = url.searchParams.get("city");
+
+  const response = await fetch(
+    `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`
+  );
+
+  return Response.json(await response.json());
+}
+```
+
+## Rules
+
+- NEVER expose API keys or secrets in client code
+- ALWAYS validate and sanitize user input
+- Use proper HTTP status codes (200, 201, 400, 401, 404, 500)
+- Handle errors gracefully with try/catch
+- 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/bundled-skills/eas-hosting/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EAS Hosting"
+  short_description: "Paid EAS service. Deploy Expo websites and Expo Router API routes to EAS Hosting, with environment secrets, custom domains, and the Cloudflare Workers runtime"
+  default_prompt: "Use $eas-hosting to deploy an Expo web app or Expo Router API routes to EAS Hosting, author +api.ts route handlers, manage hosting environment secrets and custom domains, and work within the Cloudflare Workers runtime."

package/bundled-skills/eas-observe/SKILL.md

@@ -0,0 +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 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 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. 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 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+), 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/bundled-skills/eas-observe/agents/openai.yaml

@@ -0,0 +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, ObserveInteractiveMarker, the router integrations, error reporting), query metrics with eas observe:* commands, and interpret cold/warm launch, TTR, and TTI results."

package/bundled-skills/eas-observe/references/metrics.md

@@ -0,0 +1,98 @@
+# EAS Observe metrics — interpretation cheatsheet
+
+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. 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
+
+| Metric | Full name | Target | Auto-collected? |
+|---|---|---|---|
+| Cold launch | `expo.app_startup.cold_launch_time` | **< 1.5s** | Yes (native-only — JS code does not affect it) |
+| Warm launch | `expo.app_startup.warm_launch_time` | **< 0.5s** | Yes (OS decides when warm vs cold happens) |
+| Bundle load | `expo.app_startup.bundle_load_time` | **< 0.3s** | Yes (JS load + evaluation, before `runApplication`) |
+| Time to first render (TTR) | `expo.app_startup.ttr` | **< 2s** incl. cold launch | Yes when root is wrapped with `AppMetricsRoot` (SDK 55) / `ObserveRoot` (SDK 56+) |
+| Time to interactive (TTI) | `expo.app_startup.tti` | **< 3s** incl. cold launch | **No** — call `markInteractive()` once the screen is genuinely usable |
+
+Both TTR and TTI are measured *from native launch* through the React render, so the cold-launch portion counts against them.
+
+## Interpreting TTI events (automatic params)
+
+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 |
+|---|---|---|
+| `expo.frameRate.slowFrames` | Count of frames ≥ 17ms | Main thread consistently busy during launch (heavy layout, sync bridge calls, too many components rendering) |
+| `expo.frameRate.frozenFrames` | Count of frames ≥ 700ms | Hard freezes. Even one during startup is a serious issue (sync I/O, large JSON parsing, blocking network) |
+| `expo.frameRate.totalDelay` | Total accumulated time (seconds) frames exceeded their target duration | Best single "smoothness" number — compare to TTI |
+
+**Diagnostic patterns:**
+
+- **High TTI + low totalDelay** → slow but smooth. The launch sequence itself is long. Optimize bundle size, data-fetch waterfalls, initialization chains.
+- **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.
+- The `environment` tag (defaults to `process.env.NODE_ENV`) is metadata only — it does not gate dispatch by itself.
+- Offline events are buffered on-device and flushed when the app backgrounds or `Observe.dispatchEvents()` is called.
+
+## Cross-references
+
+- Full metric definitions and optimization guidance: https://docs.expo.dev/eas/observe/reference/metrics/
+- Setup steps (`AppMetricsRoot` / `ObserveRoot`, `markInteractive`): see [`./setup.md`](./setup.md).
+- Querying metrics via the EAS CLI: see [`./queries.md`](./queries.md).