@ramonclaudio/create-vexpo 0.1.0 → 0.1.2

package/dist/templates/default/.github/workflows/check.yml

@@ -3,26 +3,34 @@ name: Check
 on:
   pull_request:
     branches: [main]
+  push:
+    branches: [main]
 
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bunx expo-doctor
-      - run: bun run typecheck
-      - run: bun run lint
-      - run: bun run format:check
-      - run: bun run test
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx expo-doctor
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm run test
 
   fingerprint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bun run fp:diff
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run fp:diff

package/dist/templates/default/.maestro/launch.yaml

@@ -1,9 +1,20 @@
-# Smoke test: app launches and the welcome screen renders.
+# Smoke test: the app cold-starts and renders without crashing, plus a screenshot.
 #
-# Maestro auto-derives the appId from the build's bundle id, so the same
-# flow runs against the dev simulator binary (`com.example.<pkg>` fallback
-# in app.config.ts) and the production binary (`com.<your-team>.<app>`)
-# without edits.
+# The UI is @expo/ui SwiftUI. `testID` props map to the native accessibilityIdentifier
+# and DO surface to Maestro as `resource-id`, so `assertVisible: { id: "..." }` resolves
+# against any tagged control or screen. Every interactive control and screen root
+# carries a stable id (grep `testID=` under src/), so real id-based flows are viable,
+# not just this no-crash smoke test.
+#
+# Driving note: Maestro taps an element's center. Buttons whose center holds content
+# (the profile card, the ProminentButton submits) tap fine by `id`. The capsule list
+# rows put a Spacer in the middle, so tap those by their label text (`tapOn: "Debug"`),
+# not by `id`, or the tap lands on empty space. Native tab-bar taps can be flaky;
+# assert-then-tap or retry.
+#
+# Maestro auto-derives the appId from the build's bundle id, so the same flow
+# runs against the dev simulator binary (`com.example.<pkg>` fallback in
+# app.config.ts) and the production binary (`com.<your-team>.<app>`) without edits.
 #
 # Run locally: `maestro test .maestro/launch.yaml`
 # Run on EAS:  triggered by `.eas/workflows/e2e-tests.yml` on every PR.
@@ -11,8 +22,6 @@ appId: ${MAESTRO_APP_ID}
 ---
 - launchApp:
     clearState: true
-- assertVisible:
-    text: "Welcome"
-    timeout: 30000
-- assertVisible: "Your new app starts here."
-- takeScreenshot: welcome
+- waitForAnimationToEnd:
+    timeout: 15000
+- takeScreenshot: launch

package/dist/templates/default/AGENTS.md

@@ -10,10 +10,9 @@ hand. These are conventions, not magic.
   calls. Everything goes through `convex/` (server) and `convex/react`
   (client). After running `npx convex ai-files install`, read
   `convex/_generated/ai/guidelines.md` before touching anything in `convex/`.
-- **Auth.** Better Auth via `@convex-dev/better-auth`. Patched locally with
-  PR #368 until upstream merges (`patches/`). Email verification is gated on
-  the `REQUIRE_EMAIL_VERIFICATION` Convex env var.
-- **Mobile.** Expo SDK 56 canary, RN 0.85, React 19. **iOS only today.**
+- **Auth.** Better Auth via `@convex-dev/better-auth@0.12.3`. Email
+  verification is gated on the `REQUIRE_EMAIL_VERIFICATION` Convex env var.
+- **Mobile.** Expo SDK 56, RN 0.85, React 19. **iOS only today.**
   Native UI exclusively via `@expo/ui/swift-ui`. No NativeWind, no Tailwind,
   no `react-native-paper`.
 - **CI/CD.** EAS Workflows (`.eas/workflows/*.yml`) for everything
@@ -45,7 +44,7 @@ hand. These are conventions, not magic.
 
 - **Convex functions**: every query/mutation needs both server-side
   validators and matching client types. The `convex/_generated/` directory is
-  the contract. Run `bunx convex codegen` after schema or function changes.
+  the contract. Run `npx convex codegen` after schema or function changes.
 - **HTTP routes** (`convex/http.ts`): every public endpoint must use
   `convex/webhook.ts` `withWebhook()` factory for HMAC verification + body
   cap + structured logging, or document why it doesn't. Inbound webhooks are
@@ -56,18 +55,36 @@ hand. These are conventions, not magic.
   `APPLE_KEY_ID`, `APPLE_SERVICES_ID`, `CONVEX_DEPLOY_KEY`).
 - **Push notifications**: only work on a physical device. iOS Simulator does
   not deliver APNs. Don't try to test push flows in the simulator.
-- **`store.config.json`**: ships with placeholder values. `bunx vexpo
+- **`store.config.json`**: ships with placeholder values. `npx vexpo
 rebrand` fills them in. App Review will reject builds with placeholder
   contact info.
 
 ## When in doubt
 
-- Run `bunx vexpo doctor` to check that `.env.local`, Convex env, EAS env,
+- Run `npx vexpo doctor` to check that `.env.local`, Convex env, EAS env,
   and `app.config.ts` agree.
-- Use `bunx eas <subcommand>` for canonical EAS operations. **Don't reinvent
+- Use `npx eas <subcommand>` for canonical EAS operations. **Don't reinvent
   EAS.** That's the vexpo design principle.
 - Read `SETUP.md` for the long-form orchestration walkthrough.
 
+## Agent setup
+
+- **Claude Code:** install Expo's official agent skills with
+  `/plugin marketplace add expo/skills` then `/plugin install expo`. For
+  Codex, Cursor, or any other agent, run `npx skills add expo/skills`. The
+  Convex agent skills install separately via `npx convex ai-files install`.
+- **Pre-approved commands:** `.claude/settings.json` allows read-only
+  `git`/`expo`/`eas`/`convex`/`vexpo` calls + the project's `npm run`
+  scripts (`typecheck`, `lint`, `test`, `format`, `dev`, `fp`) without
+  per-step permission prompts. Destructive ops (`git push`, `git reset`,
+  `npm install`, `expo deploy`) still ask.
+- **EAS Convex bootstrap:** `eas integrations:convex:connect` is the
+  upstream SDK 56 path for provisioning a Convex backend, writing
+  `CONVEX_DEPLOY_KEY` + `EXPO_PUBLIC_CONVEX_URL`, and registering the env
+  vars across Production/Preview/Development. `npx vexpo full` is the
+  broader path that also wires Better Auth, Resend, and App Store identity
+  in one shot. Use vexpo for a complete starter, EAS for Convex alone.
+
 <!-- convex-ai-start -->
 
 This project uses [Convex](https://convex.dev) as its backend.

package/dist/templates/default/DESIGN.md

@@ -158,7 +158,9 @@ In-app typography uses the same Geist face but caps at Bold (700) for nav titles
 | Body emphasis                   | 600 SemiBold | 16    | 24          | 0              |
 | Caption                         | 400 Regular  | 13-14 | 20-22       | 0              |
 
-Body and label text scales with the user's Larger Text accessibility setting via `lib/dynamic-font.ts`. The `useDynamicFont` hook multiplies the declared size by `useWindowDimensions().fontScale` before passing to `@expo/ui/swift-ui`'s `font()` modifier. Don't bypass this hook. If you do, your screen breaks at Larger Text.
+Every label scales with the user's Larger Text accessibility setting via `src/lib/dynamic-font.ts`. The `useDynamicFont` hook maps the declared point size to a SwiftUI `Font.TextStyle` and passes it to `@expo/ui/swift-ui`'s `font()` modifier (upstream `expo/expo#46007`), so the Geist family rides Apple's Dynamic Type curves natively. SwiftUI rescales the text when the setting changes, no JS re-render. The declared size is the base, so default-size rendering is unchanged. Don't bypass this hook. If you do, your text stops scaling at Larger Text.
+
+Native compact chrome does not scale with Dynamic Type, by iOS design, and that is not a bug to chase. Segmented `Picker` titles (Preferences' Appearance and Reduce Motion, the auth Sign in/Sign up and Email/Username toggles), inline navigation-bar titles, and tab-bar labels stay fixed at accessibility text sizes. SwiftUI's `pickerStyle("segmented")` renders titles in `UISegmentedControl`'s own font and ignores any `dfont` on the segments or the picker (verified on device). `react-native-screens` builds nav-title fonts at a fixed size (`scaleMultiplier: 1.0`, no `UIFontMetrics`), matching UIKit's compact inline title. Neither is `@expo/ui` or template code forcing it. iOS exposes this chrome to accessibility through the large-content HUD on long-press, not inline growth, so the behavior is correct and consistent. To make a control grow anyway you must leave the native control: reflow the segmented picker to a vertical option list at accessibility sizes, or use a large title (which does scale) instead of an inline one.
 
 Geist's variable axes are not currently exercised at runtime (we use static TTFs for individual weights via `expo-font`). The variable TTF ships in `assets/fonts/` for future use. If runtime needs variable weight interpolation, point `expo-font` at the variable file and use SwiftUI's `.fontWeight()` modifier.
 
@@ -269,17 +271,19 @@ The system uses `@expo/ui/swift-ui` primitives exclusively for native rendering.
 | `ProgressView`              | Spinner or determinate progress                                               | Loading states                         |
 | `ContentUnavailableView`    | Empty state with SF Symbol + title + description                              | Empty home, no results                 |
 
+Text inputs bind `text` to a `useNativeState("")` and mask synchronously: a `"worklet"` `onTextChange` rewrites the field on the same frame the keystroke lands (digits-only OTP, lowercase usernames), so the raw character never paints. Reusable masks live in `lib/masks.ts`.
+
 ### Custom composition (in `components/ui/`)
 
-| Component                   | Purpose                                                                       | Notes                              |
-| :-------------------------- | :---------------------------------------------------------------------------- | :--------------------------------- |
-| `Material`                  | Translucent surface with iOS 26+ Liquid Glass / iOS 16.4-25 BlurView fallback | Reserve for navigation chrome only |
-| `OfflineBanner`             | Top-of-screen notification banner using `Material` chrome variant             | Shows when network unavailable     |
-| `LoadingScreen`             | Brand-icon + spinner, themed by appearance                                    | Suspense fallback                  |
-| `ErrorBoundary`             | Top-level crash boundary with brand recovery UI                               | Wraps each route segment           |
-| `ConvexError`               | Maps Convex errors to user-readable copy                                      | Used in error displays             |
-| `Skeleton` / `SkeletonLine` | Animated loading placeholders, respect Reduce Motion                          | Profile loading, list loading      |
-| `StatusText`                | `ErrorText` + `SuccessText` with accessibility announcements                  | Form feedback                      |
+| Component                              | Purpose                                                                                                                                                                           | Notes                              |
+| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------- |
+| `Material`                             | Translucent surface with iOS 26+ Liquid Glass / iOS 16.4-25 BlurView fallback                                                                                                     | Reserve for navigation chrome only |
+| `OfflineBanner`                        | Top-of-screen notification banner using `Material` chrome variant                                                                                                                 | Shows when network unavailable     |
+| `LoadingScreen`                        | Brand-icon + spinner, themed by appearance                                                                                                                                        | Suspense fallback                  |
+| `ErrorBoundary`                        | Top-level crash boundary with brand recovery UI                                                                                                                                   | Wraps each route segment           |
+| `ConvexError`                          | Maps Convex errors to user-readable copy                                                                                                                                          | Used in error displays             |
+| `SkeletonProfile` / `SkeletonSessions` | Static loading placeholders. No animation, so nothing to suppress under Reduce Motion. Filler bars carry an empty `accessibilityLabel` so VoiceOver skips the placeholder shapes. | Profile loading, sessions loading  |
+| `StatusText`                           | `ErrorText` + `SuccessText` with accessibility announcements                                                                                                                      | Form feedback                      |
 
 ### Custom hooks (in `hooks/`)
 

package/dist/templates/default/README.md

@@ -2,20 +2,22 @@
 
 Expo SDK 56 + Convex + Better Auth + Resend, wired end-to-end for iOS. Native SwiftUI via `@expo/ui/swift-ui`, email + password + email OTP + Apple Sign In, APNs push, Universal Links, profile + active sessions with avatar uploads and device-by-device revocation. EAS for the whole build surface: 10 workflows, fingerprint-gated OTA-or-build, TestFlight, rollback, rollout, ASC events, and the Apple Sign In JWT rotation cron.
 
+A lot of the SwiftUI modifiers the template reaches for, `clipShape("capsule")`, `defaultScrollAnchorForRole`, `scrollTargetBehavior`, `scrollPosition`, `textInputAutocapitalization`, `textContentType`, the `Alert` component, the Dynamic Type pair (`textStyle` scaling on `font`, `dynamicTypeSize` bounds), `accessibilityHidden`, are upstream PRs we wrote and got merged into `expo/expo`. Full ledger in [`../../docs/UPSTREAM.md`](../../docs/UPSTREAM.md).
+
 ## Quick start
 
 ```bash
-bun install
+npm install
 
-bunx vexpo lite         # 60-second path: Convex + Better Auth, simulator-ready
-bunx vexpo lite --new   # same, plus a Convex signup walkthrough if you don't have one
+npx vexpo lite         # 60-second path: Convex + Better Auth, simulator-ready
+npx vexpo lite --new   # same, plus a Convex signup walkthrough if you don't have one
 ```
 
 Then in two terminals:
 
 ```bash
-bun run convex:dev      # terminal 1
-bun run ios             # terminal 2
+npm run convex:dev      # terminal 1
+npm run ios             # terminal 2
 ```
 
 Lite mode skips Apple / EAS / Resend entirely. `REQUIRE_EMAIL_VERIFICATION` is off on Convex so sign-up auto-verifies, the user lands in the app with one tap, and the UI hides the OTP / password-reset / change-email flows that need Resend to work.
@@ -23,33 +25,38 @@ Lite mode skips Apple / EAS / Resend entirely. `REQUIRE_EMAIL_VERIFICATION` is o
 When you're ready to ship, swap `lite` for `full`:
 
 ```bash
-bunx vexpo full         # provisions Resend, Apple Sign In, EAS, rebrand wizard
-bunx vexpo full --new   # same, plus walks Apple / Convex / Expo / Resend signups
+npx vexpo full         # provisions Resend, Apple Sign In, EAS, rebrand wizard
+npx vexpo full --new   # same, plus walks Apple / Convex / Expo / Resend signups
 ```
 
-`full` writes `.env.local`, sets Convex env vars (`REQUIRE_EMAIL_VERIFICATION=true` once Resend is wired), validates the ASC API key, signs the SIWA JWT, runs `eas init` and `eas env:push`, prompts the rebrand wizard. Prints the `eas build` command at the end. vexpo doesn't run it for you, you run `bunx eas build -p ios --profile production --auto-submit-with-profile testflight` when you're ready.
+`full` writes `.env.local`, sets Convex env vars (`REQUIRE_EMAIL_VERIFICATION=true` once Resend is wired), validates the ASC API key, signs the SIWA JWT, runs `eas init` and `eas env:push`, prompts the rebrand wizard. Prints the `eas build` command at the end. vexpo doesn't run it for you, you run `npx eas build -p ios --profile production --auto-submit-with-profile testflight` when you're ready.
 
-Run `bunx vexpo doctor` any time to auth-check every credential against the real service and cross-reference IDs across `.env.local`, Convex env, EAS env, and `app.config.ts`. Catches "wrong .p8 from another project" or ".env.prod copied from a different fork" in seconds.
+Run `npx vexpo doctor` any time to auth-check every credential against the real service and cross-reference IDs across `.env.local`, Convex env, EAS env, and `app.config.ts`. Catches "wrong .p8 from another project" or ".env.prod copied from a different fork" in seconds.
 
 Long-form walkthrough with every prompt, every env-var alternative, and recovery paths: [`SETUP.md`](./SETUP.md).
 
 ## What's wired up
 
-- Convex backend with reactive queries, storage, real-time sync, and rate limiting on every endpoint via `@convex-dev/rate-limiter`
-- Better Auth via `@convex-dev/better-auth` (sessions, accounts, devices)
+- Convex backend with reactive queries, storage, real-time sync, and `@convex-dev/rate-limiter` on every application mutation. Auth-route rate limits ship via Better Auth at the HTTP layer.
+- Better Auth via `@convex-dev/better-auth` (sessions, accounts; per-device revocation via `session.userAgent`)
+- App Attest device attestation via `@expo/app-integrity` with server-side verification in Convex
 - Resend via `@convex-dev/resend` for OTP, password reset, change-email, with webhook delivery events
-- Apple Sign In via Apple's official `AppleAuthenticationButton`, HIG-compliant BLACK/WHITE theme-aware, SIWA Services ID + ES256 JWT signing (180-day expiry, auto-rotated every 90 days)
+- Apple Sign In via Apple's official `AppleAuthenticationButton`, HIG-compliant (BLACK in dark mode, WHITE in light; `WHITE_OUTLINE` isn't used), SIWA Services ID + ES256 JWT signing (180-day expiry, auto-rotated every 90 days)
 - APNs push via `expo-notifications` with token registration on sign-in
 - Apple Universal Links from Convex's HTTP router (AASA at `/.well-known/apple-app-site-association`)
 - Profile editing with avatar uploads to Convex storage
 - Active sessions screen with device-by-device revocation
-- Theme switching, haptics toggle, reduced motion, dynamic type, VoiceOver labels everywhere
+- Account soft-delete with a 30-day grace window and a restore-or-confirm screen on next sign-in
+- Pull-to-refresh on home and sessions, plus an interactive update banner on iOS 26
+- Theme switching, haptics toggle, reduced motion, VoiceOver labels everywhere (decorative views hidden from the rotor)
+- Native Dynamic Type end to end: every label scales with the Larger Text setting via `textStyle`, bounded with `dynamicTypeSize` ceilings on the seven fixed-geometry controls that would clip instead of wrap
 - Spotlight-style search tab (debounced, scored, keyword-aware)
 - Skeleton placeholders during initial query loads
 - Debug screen at `/debug` gated by toggle, off in production by default
 - Liquid Glass on iOS 26+ via `expo-glass-effect`, UIVisualEffectView blur fallback on iOS 16.4-25 via `expo-blur`, both behind a `<Material>` primitive
-- EAS Build / Update / Submit / Metadata. `runtimeVersion: { policy: "fingerprint" }`, branch/channel model, `appVersionSource: "remote"`. ASC API key managed by EAS (`eas credentials -p ios`), no `eas.json` patches
-- 10 EAS Workflows under `.eas/workflows/`: dev builds, PR previews with `github-comment` + QR + fingerprint-gated OTA-or-build, deploy on `main`, TestFlight on `beta/*`, manual rollback / rollout, ASC event triggers to Slack, the SIWA JWT rotation cron, Maestro E2E
+- OTA updates code-signed end-to-end (`expo-updates` code signing; generate the cert with `npm run updates:gen-cert`), so only signed bundles install
+- EAS Build / Update / Submit / Metadata. `runtimeVersion: { policy: "fingerprint" }` (auto-bumps on native code changes), branch/channel model, `appVersionSource: "remote"`. ASC API key managed by EAS (`eas credentials -p ios`), no `eas.json` patches. `@expo/fingerprint >= 0.19.3` makes the policy deterministic across machines and CI out of the box, so the earlier `fingerprint.config.js` + `.fingerprintignore` jsi knobs were dropped.
+- 10 EAS Workflows under `.eas/workflows/`: dev builds, PR previews with `github-comment` + QR + fingerprint-gated OTA-or-build, production deploy, TestFlight on `beta/*`, manual rollback / rollout, ASC event triggers to Slack, the SIWA JWT rotation cron, Maestro E2E. PR previews, Maestro E2E, and the production deploy are manual-only (`workflow_dispatch`) by default: the first two to conserve EAS build credits (restore their `pull_request` triggers to run on every PR), the deploy so a merge to `main` can't build, submit, and ship an OTA by surprise (add a `push: main` trigger if you want that)
 - GitHub Actions for general-purpose checks: typecheck, lint, format, tests, fingerprint diff on PR + push to `main`
 
 ## Pre-reqs
@@ -62,92 +69,90 @@ Long-form walkthrough with every prompt, every env-var alternative, and recovery
 ## Scripts
 
 ```
-bun run dev                    Metro + dev client
-bun run start                  Metro with cleared cache
-bun run ios                    Clean prebuild + compile + run on simulator
-bun run ios:dev                Run on simulator (skip prebuild, fast)
-bun run ios:device             Clean prebuild + compile + run on physical device
-bun run prebuild               Generate iOS native project from config
-
-bun run convex:dev             Convex dev server (watch mode)
-bun run convex:deploy          Deploy Convex functions to production
-bun run convex:logs            Tail dev deployment logs
-bun run convex:logs:prod       Tail prod deployment logs
-bun run convex:env             List dev env vars
-bun run convex:env:prod        List prod env vars
-bun run convex:insights        OCC conflicts + resource limits (dev)
-bun run convex:insights:prod   Same for prod
-bun run convex:dashboard       Open the Convex dashboard
-bun run convex:codegen         Regenerate convex/_generated/
-
-bun run eas:dev                eas build -p ios --profile development:simulator
-bun run eas:dev:device         eas build -p ios --profile development:device
-bun run eas:tf                 eas build -p ios --profile production --auto-submit-with-profile testflight
-bun run eas:prod               eas build -p ios --profile production
-bun run metadata:lint          eas metadata:lint
-bun run metadata:push          eas metadata:lint && eas metadata:push
-bun run metadata:pull          eas metadata:pull
-bun run env:pull               eas env:pull --environment development
-bun run env:pull:prod          eas env:pull --environment production
-
-bun run clean                  Trash node_modules, ios, caches, then reinstall
-bun run clean:metro            Trash Metro/Babel/Haste caches only
-bun run clean:state            Wipe .setup-state.json + standard clean
-bun run typecheck              tsc --noEmit
-bun run lint                   oxlint
-bun run format                 oxfmt
-bun run format:check           oxfmt --check
-bun run test                   vitest run
-bun run test:watch             vitest
-bun run fp                     Print Expo fingerprint hash
-bun run fp:diff                Diff fingerprint vs base ref
-bun run upgrade                expo install expo@canary && expo install --fix
-bun run upgrade:stable         expo install expo@latest && expo install --fix
+npm run dev                    Metro + dev client
+npm run start                  Metro with cleared cache
+npm run ios                    Clean prebuild + compile + run on simulator
+npm run ios:dev                Run on simulator (skip prebuild, fast)
+npm run ios:device             Clean prebuild + compile + run on physical device
+npm run prebuild               Generate iOS native project from config
+
+npm run convex:dev             Convex dev server (watch mode)
+npm run convex:deploy          Deploy Convex functions to production
+npm run convex:logs            Tail dev deployment logs
+npm run convex:logs:prod       Tail prod deployment logs
+npm run convex:env             List dev env vars
+npm run convex:env:prod        List prod env vars
+npm run convex:insights        OCC conflicts + resource limits (dev)
+npm run convex:insights:prod   Same for prod
+npm run convex:dashboard       Open the Convex dashboard
+npm run convex:codegen         Regenerate convex/_generated/
+
+npm run eas:dev                eas build -p ios --profile development:simulator
+npm run eas:dev:device         eas build -p ios --profile development:device
+npm run eas:tf                 eas build -p ios --profile production --auto-submit-with-profile testflight
+npm run eas:prod               eas build -p ios --profile production
+npm run metadata:lint          eas metadata:lint
+npm run metadata:push          eas metadata:lint && eas metadata:push
+npm run metadata:pull          eas metadata:pull
+npm run env:pull               eas env:pull --environment development
+npm run env:pull:prod          eas env:pull --environment production
+
+npm run clean                  Trash node_modules, ios, caches, then reinstall
+npm run clean:metro            Trash Metro/Babel/Haste caches only
+npm run clean:state            Wipe .setup-state.json + standard clean
+npm run typecheck              tsc --noEmit
+npm run lint                   oxlint
+npm run format                 oxfmt
+npm run format:check           oxfmt --check
+npm run test                   vitest run
+npm run test:watch             vitest
+npm run fp                     Print Expo fingerprint hash
+npm run fp:diff                Diff fingerprint vs base ref
+npm run upgrade                expo install expo@next && expo install --fix
+npm run upgrade:stable         expo install expo@latest && expo install --fix
 ```
 
-Setup is one-shot, not a `package.json` script. Run `bunx vexpo lite` / `bunx vexpo full` / `bunx vexpo doctor` directly. All deletions go through `trash` (macOS Trash, recoverable).
+Setup is one-shot, not a `package.json` script. Run `npx vexpo lite` / `npx vexpo full` / `npx vexpo doctor` directly. All deletions go through `trash` (macOS Trash, recoverable).
 
 ## Project structure
 
 ```
-app/                              Expo Router screens
-  (auth)/                         Sign in, sign up, forgot/reset password
-  (app)/                          Authenticated screens
-    (tabs)/                       Tab navigation
-    welcome.tsx, profile.tsx, sessions.tsx, debug.tsx, ...
-  +native-intent.tsx              Deep link validation
-  +not-found.tsx                  404 fallback
-components/                       Reusable UI
-constants/                        Theme, layout, UI tokens
+src/
+  app/                            Expo Router screens
+    (app)/                        Authenticated stack (auth modal, tabs, profile, ...)
+      (tabs)/                     Home, search, settings
+      auth/                       Sign in, sign up, forgot/reset password (modal)
+      profile/                    index.tsx + change-password.tsx
+      welcome.tsx, sessions.tsx, restore-account.tsx, debug.tsx, ...
+    +native-intent.tsx            Deep link validation
+    +not-found.tsx                404 fallback
+  components/                     Reusable UI (auth/, ui/)
+  constants/                      Theme, layout, UI tokens
+  hooks/                          useNetwork, useTheme, useUpdates, etc.
+  lib/                            Auth client, haptics, env, deep links, native state
 convex/                           Convex backend
-hooks/                            useNetwork, useTheme, useUpdates, etc.
-lib/                              Auth client, haptics, env, deep links
 plugins/
-  with-auto-signing.js            Sets CODE_SIGN_STYLE=Automatic + DEVELOPMENT_TEAM
+  with-auto-signing.js            CODE_SIGN_STYLE=Automatic + DEVELOPMENT_TEAM
   with-pod-deployment-target.js   Forces every pod to iOS 16.4
 .eas/workflows/                   10 EAS Workflow YAML files
 .github/workflows/check.yml       Typecheck, lint, format, tests, fingerprint diff
 scripts/
   clean.ts                        Trash + reinstall
   rotate-apple-jwt.mjs            CI: re-sign JWT from env vars
-__tests__/                        Convex constants + validators + HMAC verification + deep-link
+__tests__/                        Convex + lib unit tests (validators, HMAC, deep link, schemas)
 ```
 
 ## Long-form docs
 
 - [`SETUP.md`](./SETUP.md). Every setup phase with full prompts, env-var alternatives for non-interactive runs, recovery paths.
 - [`DESIGN.md`](./DESIGN.md). Color palette, typography, spacing, radius ladder, materials, the SwiftUI primitives + custom composition surface.
+- [`../../docs/UPSTREAM.md`](../../docs/UPSTREAM.md). Every upstream PR powering the template: `@expo/ui/swift-ui` modifiers, `expo-modules-core` fixes, `expo-tools` resolution, CI workflow guards.
 - [`AGENTS.md`](./AGENTS.md). Guidance for AI coding agents working in this codebase.
 
 ## Version pinning
 
-Every `expo-*` package uses the same canary tag. Mismatched tags cause subtle runtime crashes.
-
-`package.json` overrides:
-
-- `@better-auth/passkey: 1.6.9` prevents better-auth from pulling SolidJS deps that break Metro.
-- `@expo/ui: 56.0.0-canary-20260506-03817f5` unifies the version across transitive deps.
+Every `expo-*` package tracks the same SDK 56 release. Mismatched versions cause subtle runtime crashes. `npm run upgrade:stable` runs `expo install expo@latest && expo install --fix` to roll all of them forward together; `npm run upgrade` (`expo@next`) tracks the next SDK preview.
 
-`react-native-reanimated 4.3.0` is intentionally ahead of the canary's expected 4.2.1 because Bun resolves `react-native-worklets@0.8.x` which needs Reanimated 4.3+. Listed in `expo.install.exclude` to silence the doctor warning.
+`@convex-dev/better-auth@0.12.0` is the minimum compatible with `better-auth@1.6.x` (peer-dep range is `>=1.6.9 <1.7.0`). Earlier versions peer-dep `better-auth <1.6.0` and reject the `mode` field newer better-auth adds to adapter queries, breaking signup. The template pins `better-auth@1.6.16` + `@convex-dev/better-auth@0.12.3`.
 
-`@convex-dev/better-auth@0.12.0` is the minimum compatible with `better-auth@1.6.9`. Earlier versions peer-dep `better-auth <1.6.0` and reject the `mode` field newer better-auth adds to adapter queries, breaking signup. Currently the template installs from `patches/convex-dev-better-auth-0.12.2.tgz` until [PR #368](https://github.com/get-convex/better-auth/pull/368) merges.
+`convex` is pinned `~1.40.0` for now: 1.41.0 adds a `transactionLimits` options param to `runMutation` that `@convex-dev/resend@0.2.4`'s ctx types reject, which breaks the `convex/http.ts` typecheck. Widen the range back to `^1.40.0` once resend's types accept 1.41.