Integrating Convex with Expo (React Native)
Use this skill to add, repair, extend, or harden a Convex backend for an Expo app without drifting into web-only patterns or generic React Native advice.
Use this skill for
- Adding Convex to an existing Expo or Expo Router app.
- Fixing broken environment setup, provider wiring, or generated API imports.
- Building an end-to-end feature slice: schema, indexes, backend functions, frontend hooks, and validation.
- Choosing and implementing auth for Expo + Convex.
- Uploading files from Expo URIs into Convex storage.
- Refactoring for pagination, indexes, migrations, or reusable components.
- Hardening a project before preview or production release.
Do not use this skill for
- Pure Expo UI, animation, navigation, or styling work with no Convex involvement.
- Convex projects whose frontend is not Expo or React Native.
- Generic backend architecture discussions that do not need Expo-specific environment or client wiring.
Success criteria
A good outcome should leave the project with:
- A single, correctly scoped Convex client and provider.
- Working
EXPO_PUBLIC_CONVEX_URL handling in local development and EAS.
- Backend functions that match Convex best practices for validators, auth, actions, and query performance.
- Frontend hooks using generated
api references with clear loading, empty, and error states.
- A validation pass using
scripts/validate_project.py.
- A clear path for future growth: pagination, indexes, auth wrappers, migrations, and linting.
Non-negotiables
- Keep
npx convex dev running while developing or repairing the integration.
- Read the deployment URL from
process.env.EXPO_PUBLIC_CONVEX_URL.
- Mirror that value into EAS environments for preview and production builds.
- Create exactly one
ConvexReactClient per app, outside render paths.
- Mount the provider at the true root:
app/_layout.tsx, src/app/_layout.tsx, or App.tsx.
- In Expo and React Native, set
unsavedChangesWarning: false.
- Import generated references from
convex/_generated/api rather than stringly typed names.
- Treat all client-callable Convex functions as untrusted entry points.
- Add
args validators to public functions, and prefer returns validators as well.
- Keep public wrappers thin; move repeated logic into helpers, internal functions, or custom wrappers.
- Do not use
Date.now() or new Date() inside query logic.
- Do not use Node-only APIs or third-party SDKs inside queries or mutations.
- Put external API calls, heavy compute, or Node-only libraries in
action or internalAction files; if a file starts with "use node", keep it action-only.
- Avoid
.filter() and unbounded .collect() on large tables; prefer indexes plus pagination.
- Await every promise.
- Prefer TypeScript strict mode and the official Convex ESLint plugin.
First-pass triage
Before making changes, inspect the project and classify the job.
1. Identify the app entrypoint
Check for:
app/_layout.tsx or src/app/_layout.tsx for Expo Router.
App.tsx or App.jsx for classic entrypoints.
2. Audit Convex state
Look for:
package.json dependencies: convex, expo, auth libraries, ESLint tooling.
convex/ and convex/_generated/.
.env.local, .env, .env.development, .env.production.
eas.json if cloud builds matter.
- Existing provider usage:
ConvexProvider, ConvexProviderWithClerk, or custom auth wrappers.
- Existing schema and indexes in
convex/schema.ts.
- Existing public functions with missing validators, auth checks, or pagination.
3. Run the validator
From the project root:
python scripts/validate_project.py --root <project-root>
Use --json for machine-readable output or --fail-on-warning when you want stricter gating.
4. Choose the workflow
- Bootstrap / repair baseline: missing Convex setup, env vars, provider, or generated API.
- Build a feature slice: add backend data and UI together.
- Auth: add or repair sign-in and backend authorization.
- File uploads: move media or documents from device URIs into Convex storage.
- Scale / harden: indexes, pagination, components, linting, production checklist.
- Migration: reshape existing tables or gradually move from another backend.
Workflow A — Bootstrap or repair the baseline integration
Step 1: Install or confirm the client package
npx expo install convex
Step 2: Create or reconnect the Convex project
npx convex dev
Expect this to:
- create or connect a Convex project,
- create
convex/ if missing,
- generate
convex/_generated/,
- write
EXPO_PUBLIC_CONVEX_URL to .env.local,
- and keep syncing while the command runs.
Step 3: Ensure the root provider exists
For Expo Router:
import { ConvexProvider, ConvexReactClient } from "convex/react";
import { Stack } from "expo-router";
const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
unsavedChangesWarning: false,
});
export default function RootLayout() {
return (
<ConvexProvider client={convex}>
<Stack />
</ConvexProvider>
);
}
For classic App.tsx, wrap the top-level navigation tree the same way.
Step 4: Confirm generated imports
Use:
import { api } from "../convex/_generated/api";
or the correct relative path for the project layout. Do not hand-write function names.
Step 5: Verify development and build environments
Read references/eas-env.md and ensure the same deployment URL policy is reflected in EAS.
Step 6: Validate and smoke-test
- Start the Expo app.
- Confirm
useQuery(...) moves from undefined to real data.
- Run
python scripts/validate_project.py --root <project-root>.
- If needed, scaffold the canonical example with
python scripts/scaffold_tasks_example.py --root <project-root>.
Workflow B — Build a feature slice end to end
Build each feature in the order below.
1. Model the access pattern first
Before touching code, answer:
- Is the data public, user-scoped, org-scoped, or admin-only?
- Will the list stay small, or should it paginate?
- Which fields are lookup keys and therefore need indexes?
- Does any step require an external API, AI SDK, Stripe, or Node API?
2. Design the schema
Add or extend convex/schema.ts before the function layer whenever the model is stabilising.
Use references/schema-and-indexes.md for:
- flat relational modelling,
- foreign-key indexing,
- compound indexes around actual query shapes,
- bounded array guidance,
- and pagination thresholds.
3. Implement backend functions
Use references/functions.md for the detailed patterns.
Default rules:
query for deterministic reads.
mutation for writes.
action or internalAction for external APIs, third-party SDKs, or Node-only code.
internalQuery or internalMutation for logic that should never be callable from the client.
4. Enforce access on the backend
If the feature is not public, do one of these:
- explicit
ctx.auth.getUserIdentity() checks in each function, or
- reusable custom wrappers via
convex-helpers.
See references/auth.md and references/components-and-helpers.md.
5. Wire the frontend
Use references/frontend-patterns.md.
Always handle:
- loading:
useQuery(...) === undefined,
- empty state,
- mutation pending state where relevant,
- recoverable errors,
- and pagination for unbounded lists.
6. Validate the slice
Before finishing:
- run the validator with the project root,
- run lint and typecheck if the project has them,
- verify the feature on device or simulator,
- and update or add indexes before shipping.
Workflow C — Authentication and authorization
Pick one auth story and keep the stack coherent.
Option 1: Clerk
Good when the app already uses Clerk or wants a polished auth product.
Option 2: Convex Auth
Good when you want a Convex-native auth stack and are comfortable adopting a beta library.
Option 3: Existing JWT or OIDC provider
Good when the product already depends on Auth0, WorkOS, a company IdP, or another OIDC flow.
Rules regardless of provider
- Backend authorization is mandatory; client-side gating is only for UX.
- If you persist users in Convex, index by a stable identifier such as
tokenIdentifier.
- Check ownership, organisation membership, or role on every protected function.
- Prefer helper functions or custom wrappers instead of repeating auth boilerplate.
- Use internal functions for privileged internal-only operations.
Read references/auth.md for a decision matrix and implementation patterns.
Workflow D — File uploads from Expo
Use Convex upload URLs rather than trying to push raw files through a mutation.
Recommended flow:
- public or protected mutation returns
ctx.storage.generateUploadUrl(),
- client loads the local
file:// URI with fetch(uri) and converts it to a Blob,
- client
POSTs the blob to the upload URL,
- second mutation stores the returned
storageId plus app-specific metadata,
- optional scheduled or action-based post-processing happens afterwards.
Read references/file-uploads.md.
Workflow E — Scale and harden
Once the baseline works, raise the quality bar.
Performance
- Replace
.filter() scans with indexed queries where possible.
- Replace unbounded
.collect() with take, first, or paginated queries.
- Use
usePaginatedQuery for growing feeds, notifications, and infinite-scroll screens.
- Push repeated or reusable feature areas into Convex components when boundaries are clear.
Safety
- Add validators consistently.
- Keep privileged logic behind internal functions.
- Use
ConvexError or clear return shapes for expected failures.
- Never trust IDs from the client without checking ownership or membership.
Maintainability
- Turn on
@convex-dev/eslint-plugin.
- Use TypeScript strict mode.
- Keep wrappers thin and move shared logic into plain TypeScript helpers.
- Separate
"use node" action files from regular runtime files.
Read references/production-checklist.md.
Workflow F — Migrations
When changing a live schema, prefer additive transitions.
Default migration strategy:
- add new fields or tables in a backwards-compatible way,
- dual-read or dual-write if the shape is changing,
- backfill existing documents in idempotent batches,
- switch readers and writers,
- then remove the old shape.
Use internal functions or scheduled jobs for backfills, and keep migrations restart-safe.
Read references/migrations.md.
Fast troubleshooting path
If the app is broken, check these in order:
- Is
npx convex dev running and free of TypeScript errors?
- Does
.env.local contain EXPO_PUBLIC_CONVEX_URL?
- Was Metro restarted after the env file changed?
- Is there exactly one
ConvexReactClient?
- Is the provider mounted at the real root?
- Does
convex/_generated/api exist, and are imports pointing at it correctly?
- Are public functions missing
args or returns validators?
- Is a query using
Date.now(), .filter(), or unbounded .collect()?
- Is a
"use node" file incorrectly mixing queries or mutations?
- Is auth mismatched between the client provider and the backend config?
See references/troubleshooting.md.
Available scripts
References
Load only the file that matches the current task.
- references/eas-env.md — local envs, EAS envs, and deployment URL handling.
- references/tasks-example.md — canonical minimal example for the stack.
- references/schema-and-indexes.md — schema design, indexes, query shape mapping, and pagination triggers.
- references/functions.md — query, mutation, action, internal function, validators, and runtime boundaries.
- references/frontend-patterns.md — provider placement, hook usage, loading and error states, and paginated lists.
- references/auth.md — Clerk, Convex Auth, JWT or OIDC, user mapping, and server-side authorization.
- references/file-uploads.md — upload URLs, Expo URI handling, metadata storage, and post-processing.
- references/components-and-helpers.md — Convex components and
convex-helpers patterns.
- references/migrations.md — additive rollout, backfills, dual reads and writes, and batched migrations.
- references/production-checklist.md — pre-release hardening checklist.
- references/troubleshooting.md — common failures and exact fixes.
- references/evaluation.md — how to use the bundled trigger and output eval files.
- references/sources.md — upstream docs and materials used for this rewrite.
1---
2name: integrating-convex-expo
3description: >-
4 Use this skill when working on an Expo or React Native app that uses, adds, debugs, or migrates to Convex. It covers `npx convex dev`, `EXPO_PUBLIC_CONVEX_URL` and EAS envs, `ConvexReactClient` and provider wiring in `expo-router` or `App.tsx`, generated `api` imports, schema and index design, queries, mutations, actions, auth (Clerk, Convex Auth, JWT or OIDC), file uploads from Expo URIs, pagination, migrations, and common `useQuery` or `_generated` failures. Do not use it for generic Expo UI or navigation work, or for non-Expo Convex frontends unless the task is specifically about adapting them to this mobile stack.
5compatibility: >-
6 Designed for coding-agent environments that can inspect and edit an Expo project, run shell commands such as npx and python, and optionally use the internet for current Convex and Expo documentation.
7metadata:
8 source: https://skillmd.com/skills/tristanmanchester/integrating-convex-expo
9 version: "2.0.0"
10 domain: "expo-react-native-convex"
11 keywords: "convex expo react-native expo-router eas clerk convex-auth migrations uploads"
12---
13
14# Integrating Convex with Expo (React Native)
15
16Use this skill to add, repair, extend, or harden a Convex backend for an Expo app without drifting into web-only patterns or generic React Native advice.
17
18## Use this skill for
19
20- Adding Convex to an existing Expo or Expo Router app.
21- Fixing broken environment setup, provider wiring, or generated API imports.
22- Building an end-to-end feature slice: schema, indexes, backend functions, frontend hooks, and validation.
23- Choosing and implementing auth for Expo + Convex.
24- Uploading files from Expo URIs into Convex storage.
25- Refactoring for pagination, indexes, migrations, or reusable components.
26- Hardening a project before preview or production release.
27
28## Do not use this skill for
29
30- Pure Expo UI, animation, navigation, or styling work with no Convex involvement.
31- Convex projects whose frontend is not Expo or React Native.
32- Generic backend architecture discussions that do not need Expo-specific environment or client wiring.
33
34## Success criteria
35
36A good outcome should leave the project with:
37
381. A single, correctly scoped Convex client and provider.
392. Working `EXPO_PUBLIC_CONVEX_URL` handling in local development and EAS.
403. Backend functions that match Convex best practices for validators, auth, actions, and query performance.
414. Frontend hooks using generated `api` references with clear loading, empty, and error states.
425. A validation pass using `scripts/validate_project.py`.
436. A clear path for future growth: pagination, indexes, auth wrappers, migrations, and linting.
44
45## Non-negotiables
46
47- Keep `npx convex dev` running while developing or repairing the integration.
48- Read the deployment URL from `process.env.EXPO_PUBLIC_CONVEX_URL`.
49- Mirror that value into EAS environments for preview and production builds.
50- Create exactly one `ConvexReactClient` per app, outside render paths.
51- Mount the provider at the true root: `app/_layout.tsx`, `src/app/_layout.tsx`, or `App.tsx`.
52- In Expo and React Native, set `unsavedChangesWarning: false`.
53- Import generated references from `convex/_generated/api` rather than stringly typed names.
54- Treat all client-callable Convex functions as untrusted entry points.
55- Add `args` validators to public functions, and prefer `returns` validators as well.
56- Keep public wrappers thin; move repeated logic into helpers, internal functions, or custom wrappers.
57- Do not use `Date.now()` or `new Date()` inside query logic.
58- Do not use Node-only APIs or third-party SDKs inside queries or mutations.
59- Put external API calls, heavy compute, or Node-only libraries in `action` or `internalAction` files; if a file starts with `"use node"`, keep it action-only.
60- Avoid `.filter()` and unbounded `.collect()` on large tables; prefer indexes plus pagination.
61- Await every promise.
62- Prefer TypeScript strict mode and the official Convex ESLint plugin.
63
64## First-pass triage
65
66Before making changes, inspect the project and classify the job.
67
68### 1. Identify the app entrypoint
69
70Check for:
71
72- `app/_layout.tsx` or `src/app/_layout.tsx` for Expo Router.
73- `App.tsx` or `App.jsx` for classic entrypoints.
74
75### 2. Audit Convex state
76
77Look for:
78
79- `package.json` dependencies: `convex`, `expo`, auth libraries, ESLint tooling.
80- `convex/` and `convex/_generated/`.
81- `.env.local`, `.env`, `.env.development`, `.env.production`.
82- `eas.json` if cloud builds matter.
83- Existing provider usage: `ConvexProvider`, `ConvexProviderWithClerk`, or custom auth wrappers.
84- Existing schema and indexes in `convex/schema.ts`.
85- Existing public functions with missing validators, auth checks, or pagination.
86
87### 3. Run the validator
88
89From the project root:
90
91```bash
92python scripts/validate_project.py --root <project-root>
93```
94
95Use `--json` for machine-readable output or `--fail-on-warning` when you want stricter gating.
96
97### 4. Choose the workflow
98
99- **Bootstrap / repair baseline**: missing Convex setup, env vars, provider, or generated API.
100- **Build a feature slice**: add backend data and UI together.
101- **Auth**: add or repair sign-in and backend authorization.
102- **File uploads**: move media or documents from device URIs into Convex storage.
103- **Scale / harden**: indexes, pagination, components, linting, production checklist.
104- **Migration**: reshape existing tables or gradually move from another backend.
105
106## Workflow A — Bootstrap or repair the baseline integration
107
108### Step 1: Install or confirm the client package
109
110```bash
111npx expo install convex
112```
113
114### Step 2: Create or reconnect the Convex project
115
116```bash
117npx convex dev
118```
119
120Expect this to:
121
122- create or connect a Convex project,
123- create `convex/` if missing,
124- generate `convex/_generated/`,
125- write `EXPO_PUBLIC_CONVEX_URL` to `.env.local`,
126- and keep syncing while the command runs.
127
128### Step 3: Ensure the root provider exists
129
130For Expo Router:
131
132```tsx
133import { ConvexProvider, ConvexReactClient } from "convex/react";
134import { Stack } from "expo-router";
135
136const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
137 unsavedChangesWarning: false,
138});
139
140export default function RootLayout() {
141 return (
142 <ConvexProvider client={convex}>
143 <Stack />
144 </ConvexProvider>
145 );
146}
147```
148
149For classic `App.tsx`, wrap the top-level navigation tree the same way.
150
151### Step 4: Confirm generated imports
152
153Use:
154
155```ts
156import { api } from "../convex/_generated/api";
157```
158
159or the correct relative path for the project layout. Do not hand-write function names.
160
161### Step 5: Verify development and build environments
162
163Read [references/eas-env.md](references/eas-env.md) and ensure the same deployment URL policy is reflected in EAS.
164
165### Step 6: Validate and smoke-test
166
167- Start the Expo app.
168- Confirm `useQuery(...)` moves from `undefined` to real data.
169- Run `python scripts/validate_project.py --root <project-root>`.
170- If needed, scaffold the canonical example with `python scripts/scaffold_tasks_example.py --root <project-root>`.
171
172## Workflow B — Build a feature slice end to end
173
174Build each feature in the order below.
175
176### 1. Model the access pattern first
177
178Before touching code, answer:
179
180- Is the data public, user-scoped, org-scoped, or admin-only?
181- Will the list stay small, or should it paginate?
182- Which fields are lookup keys and therefore need indexes?
183- Does any step require an external API, AI SDK, Stripe, or Node API?
184
185### 2. Design the schema
186
187Add or extend `convex/schema.ts` before the function layer whenever the model is stabilising.
188
189Use [references/schema-and-indexes.md](references/schema-and-indexes.md) for:
190
191- flat relational modelling,
192- foreign-key indexing,
193- compound indexes around actual query shapes,
194- bounded array guidance,
195- and pagination thresholds.
196
197### 3. Implement backend functions
198
199Use [references/functions.md](references/functions.md) for the detailed patterns.
200
201Default rules:
202
203- `query` for deterministic reads.
204- `mutation` for writes.
205- `action` or `internalAction` for external APIs, third-party SDKs, or Node-only code.
206- `internalQuery` or `internalMutation` for logic that should never be callable from the client.
207
208### 4. Enforce access on the backend
209
210If the feature is not public, do one of these:
211
212- explicit `ctx.auth.getUserIdentity()` checks in each function, or
213- reusable custom wrappers via `convex-helpers`.
214
215See [references/auth.md](references/auth.md) and [references/components-and-helpers.md](references/components-and-helpers.md).
216
217### 5. Wire the frontend
218
219Use [references/frontend-patterns.md](references/frontend-patterns.md).
220
221Always handle:
222
223- loading: `useQuery(...) === undefined`,
224- empty state,
225- mutation pending state where relevant,
226- recoverable errors,
227- and pagination for unbounded lists.
228
229### 6. Validate the slice
230
231Before finishing:
232
233- run the validator with the project root,
234- run lint and typecheck if the project has them,
235- verify the feature on device or simulator,
236- and update or add indexes before shipping.
237
238## Workflow C — Authentication and authorization
239
240Pick one auth story and keep the stack coherent.
241
242### Option 1: Clerk
243
244Good when the app already uses Clerk or wants a polished auth product.
245
246### Option 2: Convex Auth
247
248Good when you want a Convex-native auth stack and are comfortable adopting a beta library.
249
250### Option 3: Existing JWT or OIDC provider
251
252Good when the product already depends on Auth0, WorkOS, a company IdP, or another OIDC flow.
253
254### Rules regardless of provider
255
256- Backend authorization is mandatory; client-side gating is only for UX.
257- If you persist users in Convex, index by a stable identifier such as `tokenIdentifier`.
258- Check ownership, organisation membership, or role on every protected function.
259- Prefer helper functions or custom wrappers instead of repeating auth boilerplate.
260- Use internal functions for privileged internal-only operations.
261
262Read [references/auth.md](references/auth.md) for a decision matrix and implementation patterns.
263
264## Workflow D — File uploads from Expo
265
266Use Convex upload URLs rather than trying to push raw files through a mutation.
267
268Recommended flow:
269
2701. public or protected mutation returns `ctx.storage.generateUploadUrl()`,
2712. client loads the local `file://` URI with `fetch(uri)` and converts it to a `Blob`,
2723. client `POST`s the blob to the upload URL,
2734. second mutation stores the returned `storageId` plus app-specific metadata,
2745. optional scheduled or action-based post-processing happens afterwards.
275
276Read [references/file-uploads.md](references/file-uploads.md).
277
278## Workflow E — Scale and harden
279
280Once the baseline works, raise the quality bar.
281
282### Performance
283
284- Replace `.filter()` scans with indexed queries where possible.
285- Replace unbounded `.collect()` with `take`, `first`, or paginated queries.
286- Use `usePaginatedQuery` for growing feeds, notifications, and infinite-scroll screens.
287- Push repeated or reusable feature areas into Convex components when boundaries are clear.
288
289### Safety
290
291- Add validators consistently.
292- Keep privileged logic behind internal functions.
293- Use `ConvexError` or clear return shapes for expected failures.
294- Never trust IDs from the client without checking ownership or membership.
295
296### Maintainability
297
298- Turn on `@convex-dev/eslint-plugin`.
299- Use TypeScript strict mode.
300- Keep wrappers thin and move shared logic into plain TypeScript helpers.
301- Separate `"use node"` action files from regular runtime files.
302
303Read [references/production-checklist.md](references/production-checklist.md).
304
305## Workflow F — Migrations
306
307When changing a live schema, prefer additive transitions.
308
309Default migration strategy:
310
3111. add new fields or tables in a backwards-compatible way,
3122. dual-read or dual-write if the shape is changing,
3133. backfill existing documents in idempotent batches,
3144. switch readers and writers,
3155. then remove the old shape.
316
317Use internal functions or scheduled jobs for backfills, and keep migrations restart-safe.
318
319Read [references/migrations.md](references/migrations.md).
320
321## Fast troubleshooting path
322
323If the app is broken, check these in order:
324
3251. Is `npx convex dev` running and free of TypeScript errors?
3262. Does `.env.local` contain `EXPO_PUBLIC_CONVEX_URL`?
3273. Was Metro restarted after the env file changed?
3284. Is there exactly one `ConvexReactClient`?
3295. Is the provider mounted at the real root?
3306. Does `convex/_generated/api` exist, and are imports pointing at it correctly?
3317. Are public functions missing `args` or `returns` validators?
3328. Is a query using `Date.now()`, `.filter()`, or unbounded `.collect()`?
3339. Is a `"use node"` file incorrectly mixing queries or mutations?
33410. Is auth mismatched between the client provider and the backend config?
335
336See [references/troubleshooting.md](references/troubleshooting.md).
337
338## Available scripts
339
340- `scripts/validate_project.py`
341 - Validates the project rooted at `--root` or, if copied into a repo, the current working tree.
342 - Validates Expo and Convex dependencies.
343 - Checks env files, provider wiring, generated code, validator presence, `"use node"` misuse, and common query anti-patterns.
344 - Supports `--json`, `--root`, and `--fail-on-warning`.
345
346- `scripts/scaffold_tasks_example.py`
347 - Dry-run by default.
348 - Can generate `sampleData.jsonl`, `convex/schema.ts`, `convex/tasks.ts`, and an optional Expo screen file.
349 - Supports `--write`, `--overwrite`, `--ui-file`, and `--json`.
350
351## References
352
353Load only the file that matches the current task.
354
355- [references/eas-env.md](references/eas-env.md) — local envs, EAS envs, and deployment URL handling.
356- [references/tasks-example.md](references/tasks-example.md) — canonical minimal example for the stack.
357- [references/schema-and-indexes.md](references/schema-and-indexes.md) — schema design, indexes, query shape mapping, and pagination triggers.
358- [references/functions.md](references/functions.md) — query, mutation, action, internal function, validators, and runtime boundaries.
359- [references/frontend-patterns.md](references/frontend-patterns.md) — provider placement, hook usage, loading and error states, and paginated lists.
360- [references/auth.md](references/auth.md) — Clerk, Convex Auth, JWT or OIDC, user mapping, and server-side authorization.
361- [references/file-uploads.md](references/file-uploads.md) — upload URLs, Expo URI handling, metadata storage, and post-processing.
362- [references/components-and-helpers.md](references/components-and-helpers.md) — Convex components and `convex-helpers` patterns.
363- [references/migrations.md](references/migrations.md) — additive rollout, backfills, dual reads and writes, and batched migrations.
364- [references/production-checklist.md](references/production-checklist.md) — pre-release hardening checklist.
365- [references/troubleshooting.md](references/troubleshooting.md) — common failures and exact fixes.
366- [references/evaluation.md](references/evaluation.md) — how to use the bundled trigger and output eval files.
367- [references/sources.md](references/sources.md) — upstream docs and materials used for this rewrite.