@ramonclaudio/create-vexpo 0.1.3 → 0.1.5

package/dist/templates/default/README.md

@@ -1,11 +1,22 @@
 # vexpo
 
-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.
+An iOS app on Expo SDK 56, wired end-to-end with Convex, Better Auth, and Resend. Native SwiftUI throughout, email + password + OTP + Apple Sign In, push, and the full EAS build surface. Everything below is already wired, so you run two commands and you're in the app.
 
-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).
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ramonclaudio/vexpo/main/docs/assets/demo-app.gif" width="300" alt="Sign up, onboarding, search, and the dark-mode flip">
+  &nbsp;&nbsp;
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ramonclaudio/vexpo/main/docs/assets/screens.png" width="600" alt="Home, profile, and settings in light and dark">
+</p>
 
 ## Quick start
 
+Requires macOS and Xcode. This is an iOS-only template, and `npm run ios` builds against the simulator. See [Pre-reqs](#pre-reqs).
+
+The `vexpo` CLI ships as a dependency, so `npm install` puts it on your path:
+
 ```bash
 npm install
 
@@ -20,44 +31,22 @@ 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.
+Lite mode skips Apple, EAS, and Resend. Sign-up auto-verifies and drops you in the app with one tap. The OTP, password-reset, and change-email flows that need Resend stay hidden.
+
+## Ship path
 
 When you're ready to ship, swap `lite` for `full`:
 
 ```bash
 npx vexpo full         # provisions Resend, Apple Sign In, EAS, rebrand wizard
-npx vexpo full --new   # same, plus walks Apple / Convex / Expo / Resend signups
+npx vexpo full --new   # same, plus walks Apple, Convex, Expo, and 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 `npx eas build -p ios --profile production --auto-submit-with-profile testflight` when you're ready.
-
-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).
+`full` writes `.env.local`, sets Convex env vars, validates the ASC API key, signs the SIWA JWT, runs `eas init` and `eas env:push`, and prints the `eas build` command at the end. It never runs the build for you.
 
-## What's wired up
+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`.
 
-- 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 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
-- 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
-- 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`
+Full walkthrough with every prompt, env-var alternative, and recovery path: [`SETUP.md`](./SETUP.md).
 
 ## Pre-reqs
 
@@ -98,7 +87,7 @@ 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:metro            Trash Metro/Haste/node-compile caches only
 npm run clean:state            Wipe .setup-state.json + standard clean
 npm run typecheck              tsc --noEmit
 npm run lint                   oxlint
@@ -112,7 +101,24 @@ 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 `npx vexpo lite` / `npx vexpo full` / `npx 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`, or `npx vexpo doctor` directly. All deletions go through `trash` (macOS Trash, recoverable).
+
+## What's wired up
+
+- Convex backend, reactive queries, storage, real-time sync, per-mutation rate limiting
+- Better Auth via `@convex-dev/better-auth`, email + password + OTP + Apple Sign In, per-device session revocation
+- App Attest device-attestation primitives ready to wire (client lib + Convex verifier)
+- Resend for OTP, password reset, and change-email, with delivery webhooks
+- APNs push, Apple Universal Links, profile editing with avatar uploads
+- Account soft-delete with a 30-day grace window
+- Theme switching, haptics, reduced motion, VoiceOver, and Dynamic Type end to end
+- Liquid Glass on iOS 26+, with a `UIVisualEffectView` blur fallback on iOS 16.4-25
+- OTA updates code-signed end to end, so only signed bundles install
+- EAS Build, Update, Submit, and Metadata, with ten workflows under `.eas/workflows/`
+
+`runtimeVersion` uses the fingerprint policy with `appVersionSource: "remote"`, ASC key managed by EAS. PR previews, Maestro E2E, and the production deploy are `workflow_dispatch`-only by default. Restore the `pull_request` triggers to build on every PR, or add a `push: main` trigger to deploy on merge.
+
+For the full feature list, design system, and the upstream PRs behind it, see [`DESIGN.md`](./DESIGN.md) and [`UPSTREAM.md`](https://github.com/ramonclaudio/vexpo/blob/main/docs/UPSTREAM.md).
 
 ## Project structure
 
@@ -128,7 +134,7 @@ src/
     +not-found.tsx                404 fallback
   components/                     Reusable UI (auth/, ui/)
   constants/                      Theme, layout, UI tokens
-  hooks/                          useNetwork, useTheme, useUpdates, etc.
+  hooks/                          useNetwork, useColorScheme, useAppUpdates, etc.
   lib/                            Auth client, haptics, env, deep links, native state
 convex/                           Convex backend
 plugins/
@@ -144,15 +150,15 @@ __tests__/                        Convex + lib unit tests (validators, HMAC, dee
 
 ## 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.
+- [`SETUP.md`](./SETUP.md). Every setup phase with full prompts, env-var alternatives, recovery paths.
+- [`DESIGN.md`](./DESIGN.md). Palette, typography, spacing, materials, and the SwiftUI composition surface.
 - [`AGENTS.md`](./AGENTS.md). Guidance for AI coding agents working in this codebase.
+- [`UPSTREAM.md`](https://github.com/ramonclaudio/vexpo/blob/main/docs/UPSTREAM.md). Every upstream PR powering the template.
 
 ## Version pinning
 
-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.
+Every `expo-*` package tracks the same SDK 56 release. Mismatched versions cause subtle runtime crashes. `npm run upgrade:stable` rolls them all forward together. `npm run upgrade` tracks the next SDK preview.
 
-`@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.x` (`0.12.3` peer-deps `better-auth >=1.6.11 <1.7.0`). Earlier versions peer-dep `better-auth <1.6.0` and reject the `mode` field newer better-auth adds to adapter queries, which breaks signup. The template pins `better-auth@1.6.16` and `@convex-dev/better-auth@0.12.3`.
 
-`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.
+`convex` is pinned `~1.40.0` for now. 1.41.0 adds a `transactionLimits` param to `runMutation` that `@convex-dev/resend@0.2.4`'s ctx types reject, which breaks the `convex/http.ts` typecheck. Widen back to `^1.40.0` once resend's types accept 1.41.

package/dist/templates/default/SETUP.md

@@ -54,6 +54,8 @@ Use it to:
 
 `--dry-run` does not hit the network for verification, doesn't prompt for credentials, doesn't write state. It only reads what already exists locally and prints the plan.
 
+`lite` and `full` also accept `--plan`. It prints the full setup journey upfront, every phase and human gate (async waits, web-UI clicks, automated steps), with costs and links, then exits. `--plan` is the map of the whole trip. `--dry-run` is what the next run does against current state. Neither writes anything.
+
 ## What `npx vexpo full` does
 
 The orchestrator runs the following phases in order, skipping any that are cached fresh in `.setup-state.json`. Each phase is also runnable standalone via `npx vexpo <phase-name>`.
@@ -69,6 +71,7 @@ The orchestrator runs the following phases in order, skipping any that are cache
 | 6     | `npx vexpo full` (EAS phase)           | eas   | Thin wrapper: `eas init` + `eas env:push` from `.env.local`                                                    |
 | 7     | `npx vexpo apple asc-key`              | ours  | Validate ASC API key against ASC `/v1/apps` (no upload)                                                        |
 | 7.5   | `npx vexpo apple credentials`          | ours  | Wraps `eas credentials -p ios`. Pre-passes cached ASC creds, EAS auto-generates dist cert + profile + push key |
+| 7.6   | `npx vexpo asc:connect`                | eas   | Wraps `eas integrations:asc:connect`, links the EAS project to its ASC app so `eas submit` resolves the bundle |
 | 8     | `npx vexpo apple services-id`          | ours  | Attach SIWA capability via ASC API (manual: create the Services ID itself)                                     |
 | 9     | `npx vexpo apple jwt`                  | ours  | Sign SIWA ES256 client_secret JWT, push to Convex env                                                          |
 | 10    | `npx vexpo apple eas-rotation-secrets` | ours  | Push the 5 EAS production secrets the JWT rotation cron needs                                                  |
@@ -136,7 +139,7 @@ Edits:
 - `app.config.ts`, `name`, `slug`, `scheme`, `BUNDLE_ID` env-var fallback
 - `app.json`, clears stale `extra.eas.projectId` (next `eas init` regenerates)
 - `package.json`, `name`, `version` reset to `0.1.0`
-- `store.config.json`, regenerated from example with prompted values
+- `store.config.json`, edited in place with prompted values (ships committed with placeholders)
 
 Backups land in `.rebrand-backup/<timestamp>/` before any write. Idempotent: re-runs detect "already rebranded" via state and skip unless `--force` is passed.
 
@@ -166,7 +169,9 @@ Prompts once for a Resend full-access key (or reads `RESEND_FULL_ACCESS_KEY`). P
 - A scoped sending key named `<pkg.name>` (deletes any existing key with the same name first)
 - A webhook pointing at `<convex-site-url>/resend-webhook`, signed with a fresh secret
 
-Sets on Convex: `RESEND_API_KEY`, `RESEND_WEBHOOK_SECRET`, `EMAIL_FROM=<pkg.name>@<domain>`, `RESEND_TEST_MODE=false`.
+Sets on Convex: `RESEND_API_KEY`, `RESEND_WEBHOOK_SECRET`, `EMAIL_FROM=<pkg.name>@<domain>`, `RESEND_TEST_MODE=false`, `REQUIRE_EMAIL_VERIFICATION=true`.
+
+`REQUIRE_EMAIL_VERIFICATION=true` flips sign-up to require an OTP before the account activates (now that real email sends).
 
 `RESEND_TEST_MODE=true` (default at provision time, flipped to `false` here) sends OTPs to Convex logs instead of real email, useful during local dev. Override `EMAIL_FROM` via `--from`.
 
@@ -201,7 +206,7 @@ Pass `--email` / `--password` to override the values from `store.config.json`. S
 
 ## Phase 6: EAS (auto, no standalone command, runs as part of `vexpo full`)
 
-Runs `eas init` (creates the project, or links to an existing one) and writes `extra.eas.projectId` to `app.json`. Mirrors every `EXPO_PUBLIC_*` from `.env.local` to the EAS `development` environment using `npx eas env:create --visibility plaintext`. Prod and preview values come from `.env.prod` via `vexpo env push`, which routes to `["production", "preview"]`.
+Runs `eas init` (creates the project, or links to an existing one) and writes `extra.eas.projectId` to `app.json`. Mirrors every `EXPO_PUBLIC_*` from `.env.local` to the EAS `development` environment using `eas env:push --path .env.local --environment development --force`. Prod and preview values come from `.env.prod` via `vexpo env push`, which routes to `["production", "preview"]`.
 
 After this, `expo prebuild` and `eas build` both find the right project + env. The `extra.eas.projectId` write also enables `app.config.ts → updates.url`.
 
@@ -223,7 +228,7 @@ Walks you to https://appstoreconnect.apple.com/access/integrations/api, prints s
 3. Click "Generate". The key cannot be retrieved later, save the .p8 file.
 4. From the table: copy the Issuer ID (above the table) and the Key ID.
 
-Then prompts for issuer ID, key ID, and `.p8` path. Validates by signing an ES256 JWT and calling `GET /v1/apps`. Re-prompts up to 3x with specific error messaging on failure (`401` = bad token, `403` = role insufficient, etc.).
+Then prompts for issuer ID, key ID, and `.p8` path. Validates by signing an ES256 JWT and calling `GET /v1/apps`. A bad key fails immediately with the reason (`401` = bad token, `403` = role insufficient, etc.), and you re-run the command. The only retry is 5 attempts on transient HTTP `429`/`5xx`, honoring `Retry-After`.
 
 Records `{issuerId, keyId, p8Path, validatedAt}` in `.setup-state.json`. The .p8 file itself stays where you put it, vexpo never copies it.
 
@@ -310,7 +315,7 @@ Rotate without re-prompting IDs: `npx vexpo apple jwt --rotate`.
 
 ### JWT rotation
 
-Apple caps `client_secret` JWTs at 180 days. The `.eas/workflows/rotate-apple-jwt.yml` cron fires every 90 days, signs a fresh JWT, and pushes it to your prod Convex deployment. Runs on EAS infrastructure with all secrets read from EAS env (production, secret visibility), no GitHub repo secrets needed. Set up once, never think about it again. Manual fallback: `npx vexpo apple jwt --rotate`.
+Apple caps `client_secret` JWTs at 180 days. The `.eas/workflows/rotate-apple-jwt.yml` cron (`0 12 1 */3 *`) fires quarterly, at 12:00 UTC on the 1st of Jan, Apr, Jul, and Oct, signs a fresh JWT, and pushes it to your prod Convex deployment. Runs on EAS infrastructure with all secrets read from EAS env (production, secret visibility), no GitHub repo secrets needed. Set up once, never think about it again. Manual fallback: `npx vexpo apple jwt --rotate`.
 
 ## Phase 10: EAS rotation secrets (`npx vexpo apple eas-rotation-secrets`)
 
@@ -386,6 +391,7 @@ Each known env-var has a fixed routing in `vexpo`'s env-files module ([source](h
 | `RESEND_API_KEY`                        | dev               | prod              | n/a                   |
 | `RESEND_WEBHOOK_SECRET`                 | dev               | prod              | n/a                   |
 | `RESEND_TEST_MODE`, `EMAIL_FROM`        | dev               | prod              | n/a                   |
+| `REQUIRE_EMAIL_VERIFICATION`            | dev               | prod              | n/a                   |
 | `APP_NAME`, `SITE_URL`, `APP_BUNDLE_ID` | dev               | prod              | n/a                   |
 | `APPLE_CLIENT_ID`                       | dev               | prod              | n/a                   |
 | `APPLE_CLIENT_SECRET`                   | dev               | prod              | n/a                   |
@@ -400,7 +406,6 @@ The five rotation-cron secrets (`APPLE_TEAM_ID`, `APPLE_KEY_ID`, `APPLE_SERVICES
 Notes:
 
 - `APPLE_SERVICES_ID` is renamed to `APPLE_CLIENT_ID` on Convex (Better Auth's expected key name).
-- GitHub secrets only get pushed from `.env.prod`, they're consumed by the prod-only JWT rotation cron.
 - `CONVEX_DEPLOYMENT` is ignored entirely (file-local pointer used by the Convex CLI, not synced).
 - Anything else is reported as "unrecognized" and skipped.
 
@@ -453,7 +458,7 @@ npx vexpo doctor --json             # machine-readable output
 npx vexpo doctor --strict           # exit non-zero on warnings
 ```
 
-Runs a battery of checks that auth-test each credential and cross-reference the values across `.env.local`, Convex env, EAS env, GitHub secrets, and `app.config.ts`. Lite mode runs the same battery automatically after sync (skip with `--no-verify`). Results are grouped by category:
+Runs a battery of checks that auth-test each credential and cross-reference the values across `.env.local`, Convex env, EAS env, and `app.config.ts`. Lite mode runs the same battery automatically after sync (skip with `--no-verify`). Results are grouped by category:
 
 | Category    | What's checked                                                                                                                                                                                                                                                                                                               |
 | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -488,14 +493,14 @@ npx eas metadata:push                                          # push store.conf
 npx eas credentials -p ios                                     # manage iOS dist cert / profile / keys
 ```
 
-EAS Workflows (`.eas/workflows/`) automate these for you on push to `main`, push tag `v*`, push to `beta/*`, on PR, and on `eas workflow:run`.
+EAS Workflows (`.eas/workflows/`) automate these. `release.yml` runs on push of a `v*` tag, `testflight.yml` on push to `beta/*`, `rotate-apple-jwt.yml` on a quarterly cron. The rest (`deploy-production.yml`, `pr-preview.yml`, `e2e-tests.yml`, `rollback.yml`, `rollout.yml`, `development-builds.yml`) are `workflow_dispatch` only. Nothing runs on push to `main` or on PR. `asc-events.yml` fires on App Store Connect events.
 
 ## Recovery: rotating things
 
 | Thing                      | Command                                                          |
 | -------------------------- | ---------------------------------------------------------------- |
 | Convex deployment          | `npx vexpo full --fresh`                                         |
-| Better Auth secret         | `npx vexpo better-auth --force`                                  |
+| Better Auth secret         | `npx vexpo better-auth --rotate-secret`                          |
 | Resend key + webhook       | `npx vexpo resend`                                               |
 | Apple Sign In JWT (manual) | `npx vexpo apple jwt --rotate`                                   |
 | Apple Sign In JWT (auto)   | EAS Workflows → `rotate-apple-jwt` → Run                         |
@@ -504,6 +509,16 @@ EAS Workflows (`.eas/workflows/`) automate these for you on push to `main`, push
 | EAS rotation secrets       | `npx vexpo apple eas-rotation-secrets --force`                   |
 | State cache                | `trash .setup-state.json`                                        |
 
+## Other commands
+
+For migrations and out-of-band fixes:
+
+- `npx vexpo adopt`, finish a project created by `eas integrations:convex:connect` (adopts the existing dev deployment, backfills site URLs + Better Auth, prints the commands left to run).
+- `npx vexpo convex:migrate --from <dep>`, copy server-side Convex env (`BETTER_AUTH_SECRET`, `RESEND_*`, `APPLE_*`, `APP_*`) from another deployment onto the current one. `CONVEX_*` left untouched.
+- `npx vexpo env convex-key [--mint]`, sync the Convex deploy key to EAS env after a deployment migration (`env push` skips these on purpose). `--mint` mints a prod key via the Platform API if EAS lacks one.
+- `npx vexpo apple jwt --copy-from <dep>`, copy `APPLE_*` env from another deployment instead of signing. No `.p8` needed.
+- `npx vexpo resend --repoint`, move the webhook to the current `convex.site` and realign the secret, without rotating the sending key or changing auth policy.
+
 ## Recovery: things break
 
 `.setup-state.json` corrupt or schema mismatch:
@@ -568,7 +583,7 @@ Use `--no-state` to ignore the local state cache. Provide every interactive valu
 | EAS env (`npx eas env:list`)       | Build-time env per environment + rotation cron secrets | written by the EAS phase of `vexpo full` + `npx vexpo apple eas-rotation-secrets` |
 | `app.config.ts`                    | Expo app config (reads `.env.local`)                   | edited by rebrand                                                                 |
 | `app.json`                         | Static `eas.projectId`                                 | written by `eas init`                                                             |
-| `store.config.json`                | App Store metadata + review contact                    | edited by rebrand, gitignored                                                     |
+| `store.config.json`                | App Store metadata + review contact                    | committed with placeholders, edited in place by rebrand                           |
 | `package.json`                     | Project metadata                                       | edited by rebrand                                                                 |
 
 ## State schema
@@ -610,15 +625,15 @@ Atomic writes via `tmp + rename`. Schema mismatches fail-loud, `setup` will refu
 
 ## Security
 
-| Class                 | Lives in                                                       | Rotates                                                   |
-| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------- |
-| `BETTER_AUTH_SECRET`  | Convex env                                                     | rotate via `npx vexpo better-auth --force`                |
-| Resend sending key    | Convex env (`RESEND_API_KEY`)                                  | `npx vexpo resend` deletes the named key + recreates      |
-| Resend webhook secret | Convex env (`RESEND_WEBHOOK_SECRET`)                           | rotated alongside the key                                 |
-| Apple Sign In JWT     | Convex env (`APPLE_CLIENT_SECRET`)                             | 180-day max, auto-rotated by EAS Workflows cron every 90d |
-| Apple Sign In `.p8`   | EAS env `APPLE_P8_PRIVATE_KEY` (secret visibility, production) | rotate the key in Apple Developer Console                 |
-| ASC API `.p8`         | filesystem (path you choose) + state cache                     | manual, rotate via App Store Connect → Integrations       |
-| `CONVEX_DEPLOY_KEY`   | EAS env (production, secret visibility)                        | rotate at Convex Dashboard → Settings → Deploy Keys       |
+| Class                 | Lives in                                                       | Rotates                                                       |
+| --------------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`  | Convex env                                                     | rotate via `npx vexpo better-auth --rotate-secret`            |
+| Resend sending key    | Convex env (`RESEND_API_KEY`)                                  | `npx vexpo resend` deletes the named key + recreates          |
+| Resend webhook secret | Convex env (`RESEND_WEBHOOK_SECRET`)                           | rotated alongside the key                                     |
+| Apple Sign In JWT     | Convex env (`APPLE_CLIENT_SECRET`)                             | 180-day max, auto-rotated quarterly by the EAS Workflows cron |
+| Apple Sign In `.p8`   | EAS env `APPLE_P8_PRIVATE_KEY` (secret visibility, production) | rotate the key in Apple Developer Console                     |
+| ASC API `.p8`         | filesystem (path you choose) + state cache                     | manual, rotate via App Store Connect → Integrations           |
+| `CONVEX_DEPLOY_KEY`   | EAS env (production, secret visibility)                        | rotate at Convex Dashboard → Settings → Deploy Keys           |
 
 `.setup-state.json` only stores resource IDs, file paths, and timestamps, not secrets. Safe to share for debugging.
 

package/dist/templates/default/_easignore

@@ -18,5 +18,4 @@ docs/
 .agents/
 .claude/
 app-store/
-.husky/
 convex/*.test.ts

package/dist/templates/default/_env.example

@@ -1,10 +1,11 @@
-# .env.local template. Copy to .env.local then run `npm run setup`.
-# `npm run setup` writes most of these for you. The two identity vars
-# (EXPO_PUBLIC_APP_BUNDLE_ID and EXPO_PUBLIC_APPLE_TEAM_ID) are prompted by
-# `npm run setup:convex`. Edit by hand if you prefer.
+# .env.local template. Copy to .env.local then run `npx vexpo full`.
+# `npx vexpo full` writes most of these for you (`npx vexpo lite` for the
+# dev-only subset). The two identity vars (EXPO_PUBLIC_APP_BUNDLE_ID and
+# EXPO_PUBLIC_APPLE_TEAM_ID) are prompted by `npx vexpo convex`. Edit by hand
+# if you prefer.
 
 # ---------------------------------------------------------------------------
-# Convex deployment (written by `npm run setup:convex`)
+# Convex deployment (written by `npx vexpo convex`)
 # ---------------------------------------------------------------------------
 CONVEX_DEPLOYMENT=
 EXPO_PUBLIC_CONVEX_URL=
@@ -12,7 +13,7 @@ EXPO_PUBLIC_CONVEX_SITE_URL=
 EXPO_PUBLIC_SITE_URL=
 
 # ---------------------------------------------------------------------------
-# iOS identity (prompted by `npm run setup:convex`, also pushed to Convex env)
+# iOS identity (prompted by `npx vexpo convex`, also pushed to Convex env)
 # ---------------------------------------------------------------------------
 # Reverse-DNS bundle id, e.g. com.you.vexpo.
 EXPO_PUBLIC_APP_BUNDLE_ID=
@@ -26,9 +27,13 @@ EXPO_PUBLIC_APPLE_TEAM_ID=
 # EXPO_PUBLIC_EXPO_OWNER=
 # Toggles `name` to "Vexpo (Dev)" so dev and prod can install side-by-side.
 # APP_VARIANT=development
-# Pre-fills the full-access Resend key for `npm run setup:resend` (else prompts).
+# Pre-fills the full-access Resend key for `npx vexpo resend` (else prompts).
 # RESEND_FULL_ACCESS_KEY=
-# Skips prompts in `npm run setup:apple` / `setup:asc`.
-# APPLE_P8_PATH=
-# APPLE_AUTH_KEY_PATH=
+# Apple credential overrides. The CLI reads these from the shell environment,
+# not this file, so export them before running. The APPLE_ASC_* trio skips the
+# `npx vexpo apple asc-key` prompts. APPLE_P8_PATH skips the .p8 prompt in
+# `npx vexpo apple jwt`.
 # APPLE_ASC_ISSUER_ID=
+# APPLE_ASC_KEY_ID=
+# APPLE_ASC_P8_PATH=
+# APPLE_P8_PATH=

package/dist/templates/default/app.config.ts

@@ -16,17 +16,17 @@ const pkg = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf
 
 const IS_DEV = process.env.APP_VARIANT === "development";
 
-// Identity comes from .env.local (written by `npm run setup:convex`). Fallbacks
+// Identity comes from .env.local (written by `npx vexpo convex`). Fallbacks
 // keep `expo prebuild` from crashing on a fresh checkout, but a real build
 // requires real values.
 const BUNDLE_ID = process.env.EXPO_PUBLIC_APP_BUNDLE_ID ?? `com.example.${pkg.name}`;
 const APPLE_TEAM_ID = process.env.EXPO_PUBLIC_APPLE_TEAM_ID ?? "ABCDE12345";
 const EXPO_OWNER = process.env.EXPO_PUBLIC_EXPO_OWNER ?? undefined;
 
-// Support contact surface. Populated by `vexpo rebrand` from `store.config.json`
-// once the user creates one (needed only for App Store submission). On a fresh
-// checkout these are empty and `app/(app)/help.tsx` hides the corresponding
-// buttons gracefully.
+// Support contact surface. `store.config.json` ships committed with
+// placeholders; `vexpo rebrand` fills it in (needed only for App Store
+// submission). On a fresh checkout these stay empty and `app/(app)/help.tsx`
+// hides the corresponding buttons gracefully.
 type StoreConfig = {
   apple: {
     copyright?: string;

package/dist/templates/default/convex/pushTokens.ts

@@ -2,7 +2,7 @@ import { v } from "convex/values";
 
 import { internal } from "./_generated/api";
 import { internalMutation, internalQuery } from "./_generated/server";
-import { authMutation, authQuery } from "./functions";
+import { authMutation } from "./functions";
 import { rateLimitWithThrow } from "./rateLimit";
 import { deviceTypeValidator } from "./validators";
 
@@ -76,31 +76,6 @@ export const remove = authMutation({
   },
 });
 
-export const list = authQuery({
-  args: {},
-  returns: v.array(
-    v.object({
-      _id: v.id("pushTokens"),
-      _creationTime: v.number(),
-      userId: v.string(),
-      token: v.string(),
-      deviceType: deviceTypeValidator,
-      createdAt: v.number(),
-      updatedAt: v.number(),
-      lastSeenAt: v.optional(v.number()),
-      revoked: v.optional(v.boolean()),
-      revokedAt: v.optional(v.number()),
-      lastErrorCode: v.optional(v.string()),
-    }),
-  ),
-  handler: async (ctx) => {
-    return ctx.db
-      .query("pushTokens")
-      .withIndex("by_user", (q) => q.eq("userId", ctx.user._id))
-      .collect();
-  },
-});
-
 export const removeAll = authMutation({
   args: {},
   returns: v.null(),

package/dist/templates/default/convex/rateLimit.ts

@@ -4,21 +4,6 @@ import { components } from "./_generated/api";
 import type { MutationCtx } from "./_generated/server";
 
 export const rateLimiter = new RateLimiter(components.rateLimiter, {
-  apiRead: {
-    kind: "token bucket",
-    rate: 100,
-    period: MINUTE,
-    capacity: 20,
-    shards: 2,
-  },
-
-  apiWrite: {
-    kind: "token bucket",
-    rate: 30,
-    period: MINUTE,
-    capacity: 10,
-  },
-
   userAction: {
     kind: "token bucket",
     rate: 60,
@@ -44,12 +29,7 @@ export const rateLimiter = new RateLimiter(components.rateLimiter, {
   avatarUpload: { kind: "token bucket", rate: 30, period: HOUR, capacity: 10 },
 });
 
-export type RateLimitName =
-  | "apiRead"
-  | "apiWrite"
-  | "userAction"
-  | "criticalAction"
-  | "avatarUpload";
+export type RateLimitName = "userAction" | "criticalAction" | "avatarUpload";
 
 export async function rateLimitWithThrow(
   ctx: MutationCtx,

package/dist/templates/default/convex/users.ts

@@ -8,12 +8,7 @@ import { authComponent, authUserValidator } from "./auth";
 import { validationError } from "./errors";
 import { authMutation, optionalAuthQuery } from "./functions";
 import { rateLimitWithThrow } from "./rateLimit";
-import {
-  paginatedUsersValidator,
-  publicUserProfileValidator,
-  userProfileUpdateFields,
-  validateBio,
-} from "./validators";
+import { publicUserProfileValidator, userProfileUpdateFields, validateBio } from "./validators";
 
 export const getMe = optionalAuthQuery({
   args: {},
@@ -58,49 +53,6 @@ export const getUser = optionalAuthQuery({
   },
 });
 
-export const listUsers = optionalAuthQuery({
-  args: {
-    cursor: v.optional(v.string()),
-    limit: v.optional(v.number()),
-  },
-  returns: paginatedUsersValidator,
-  handler: async (ctx, args) => {
-    const limit = Math.min(Math.max(args.limit ?? 20, 1), 100);
-
-    const results = await ctx.db
-      .query("users")
-      .order("desc")
-      .paginate({ cursor: args.cursor ?? null, numItems: limit });
-
-    const page = await Promise.all(
-      results.page.map(async (user) => {
-        const authUser = await authComponent.getAnyUserById(ctx, user.authId);
-        if (!authUser) return null;
-        const avatarUrl = user.avatar
-          ? await ctx.storage.getUrl(user.avatar)
-          : (authUser.image ?? null);
-        return {
-          _id: user._id,
-          _creationTime: user._creationTime,
-          name: authUser.name,
-          username:
-            (authUser as { displayUsername?: string | null }).displayUsername ??
-            (authUser as { username?: string | null }).username ??
-            null,
-          avatarUrl,
-          bio: user.bio,
-        };
-      }),
-    );
-
-    return {
-      page: page.filter((entry): entry is NonNullable<typeof entry> => entry !== null),
-      continueCursor: results.continueCursor,
-      isDone: results.isDone,
-    };
-  },
-});
-
 export const updateProfile = authMutation({
   args: userProfileUpdateFields,
   returns: v.id("users"),

package/dist/templates/default/convex/validators.ts

@@ -1,11 +1,6 @@
 import { literals } from "convex-helpers/validators";
 import { v } from "convex/values";
 
-export const paginatedResponseFields = {
-  continueCursor: v.string(),
-  isDone: v.boolean(),
-};
-
 // Name changes go through Better Auth (authClient.updateUser) directly.
 export const userProfileUpdateFields = {
   bio: v.optional(v.string()),
@@ -20,11 +15,6 @@ export const publicUserProfileValidator = v.object({
   bio: v.optional(v.string()),
 });
 
-export const paginatedUsersValidator = v.object({
-  page: v.array(publicUserProfileValidator),
-  ...paginatedResponseFields,
-});
-
 export const deviceTypeValidator = literals("ios");
 
 const BIO_MAX_LENGTH = 500;

package/dist/templates/default/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexpo",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "main": "expo-router/entry",
   "scripts": {

package/dist/templates/default/scripts/README.md

@@ -4,29 +4,45 @@ Build and maintenance scripts. Setup orchestration lives in the published `vexpo
 
 ## What's in this directory
 
-| Script                 | What it does                                                                                                                    |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `clean.ts`             | Trash + reinstall. `--metro` for cache-only nuke (Metro/Babel/Haste). `--state` also wipes `.setup-state.json`.                 |
-| `rotate-apple-jwt.mjs` | Re-signs the Apple Sign In `client_secret` JWT from env vars only. Used by `.eas/workflows/rotate-apple-jwt.yml` every 90 days. |
-| `_run.mjs`             | Runtime selector for `clean.ts`. Picks `bun` if available, falls back to `tsx`. Not used by the CLI.                            |
+| Script                 | What it does                                                                                                                                                                                                                        |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clean.ts`             | Trash + reinstall. `--metro` for cache-only nuke (Metro/Haste/node-compile-cache). `--state` also wipes `.setup-state.json`.                                                                                                        |
+| `gen-update-cert.mjs`  | One-shot OTA update code-signing setup. Wraps `npx expo-updates codesigning:generate`, writes `certs/certificate.pem` (committed) and `../keys/private-key.pem` (gitignored). Run via `npm run updates:gen-cert -- --name "<Org>"`. |
+| `rotate-apple-jwt.mjs` | Re-signs the Apple Sign In `client_secret` JWT from env vars only. Used by `.eas/workflows/rotate-apple-jwt.yml` every 90 days.                                                                                                     |
+| `_run.mjs`             | Runtime selector for `clean.ts`. Picks `bun` if available, falls back to `tsx`. Not used by the CLI.                                                                                                                                |
 
 Anything else (preflight checks, env validation, version bumps) lives in the `vexpo` CLI or in `eas-cli` directly.
 
+## Cleaning
+
+```bash
+npm run clean              # trash + reinstall
+npm run clean:metro        # just Metro/Haste/node-compile-cache
+npm run clean:state        # also wipe .setup-state.json
+```
+
+These run through `_run.mjs`, which picks `bun` if it's on PATH and falls back to `tsx`. To call it without the npm script: `node scripts/_run.mjs scripts/clean.ts --metro`.
+
 ## Setup orchestration
 
-Use the `vexpo` CLI:
+Use the `vexpo` CLI. `lite` and `full` are alternatives, pick the path you need:
 
 ```bash
 npx vexpo lite               # dev-mode setup (Convex + Better Auth only)
 npx vexpo full               # full provisioning to TestFlight-ready
+```
+
+The rest are independent maintenance commands, run them when you need them:
+
+```bash
 npx vexpo doctor             # cross-source drift detection
-npx vexpo env push           # sync from .env.local + .env.prod to Convex/EAS
+npx vexpo env push           # sync from .env.local + .env.prod to Convex and EAS
 npx vexpo apple asc-key      # validate ASC API key
 npx vexpo apple services-id  # attach SIWA capability to App ID
 npx vexpo apple jwt          # sign client_secret JWT, push to Convex
 ```
 
-Version bumps run through `eas build:version:set` / `eas build:version:sync` (`appVersionSource: "remote"` in `eas.json` puts EAS in charge of the version).
+Version bumps run through `eas build:version:set` or `eas build:version:sync`. `appVersionSource: "remote"` in `eas.json` puts EAS in charge of the version.
 
 The CLI itself ships from [`@ramonclaudio/vexpo` on npm](https://www.npmjs.com/package/@ramonclaudio/vexpo). Source lives at [`github.com/ramonclaudio/vexpo`](https://github.com/ramonclaudio/vexpo).