• Auto-detect existing Convex / Vercel / .vercel / .env.local state
• Read local dev env vars and propose them as prod values (the user confirms or overrides)
• Only ask the user for values that genuinely change between dev and prod (live Stripe keys, prod domain, OAuth callback updates)

Optional flag the user can pass in their message:

• "skip postdeploy" → stop after the first deploy succeeds (don't run the OAuth/Stripe webhook walkthrough)
• "dry-run" → print every command but don't execute. Useful to inspect.

<state_variables> Persist across all steps:

</state_variables>

<entry_point> Load steps/step-00-init.md </entry_point>

<step_files>

<workflow_diagram>

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Step 00     │───►│  Step 01     │───►│  Step 02     │
│  Preflight   │    │  Convex prod │    │  Vercel      │
└──────────────┘    └──────────────┘    └──────────────┘
                                               │
       ┌───────────────────────────────────────┘
       ▼
┌──────────────┐    ┌──────────────┐
│  Step 03     │───►│  Step 04     │
│  Deploy      │    │  Postdeploy  │
└──────────────┘    └──────────────┘

</workflow_diagram>

<important_files> Files this workflow may create or modify (root paths):

Files this workflow READS:

• .env and .env.local (source of truth for local secrets to mirror)
• convex/**/*.ts (to verify which env vars Convex actually consumes)
• src/lib/env.ts (to verify which env vars the Vercel runtime needs)
• src/site-config.ts (domain context) and convex/http.ts + convex/stripe/actions.ts (Stripe webhook lives in Convex, not in src/routes/api/)
• package.json (to confirm build script and Convex/Vercel CLI availability)

</important_files>

<stack_context> This project is NowStack v2:

• Backend: Convex (no Postgres / no Prisma)
• Frontend: Vite + TanStack Start + Nitro (deployed as a Node.js / serverless app on Vercel)
• Auth: Better Auth via @convex-dev/better-auth component (lives entirely in Convex)
• Email: Resend via @convex-dev/resend component (Resend API key in Convex env)
• Payments: Stripe via custom Convex actions (convex/stripe/actions.ts). The webhook is a Convex httpAction mounted at https://<deployment>.convex.site/stripe/webhook (registered with Stripe via node scripts/setup-stripe-webhook.mjs). Webhooks never hit Vercel — there is no TanStack webhook route.
• File upload: Cloudflare R2 via Convex actions in convex/files/actions.ts

TWO places env vars must be set for prod to work:

1. Convex prod env (server-side secrets used inside convex/** functions): set via npx convex env set --prod KEY value
2. Vercel project env only stores deploy keys: CONVEX_DEPLOY_KEY for Production/Preview and CONVEX_PROD_DEPLOY_KEY for Preview production snapshot imports.

The Vercel build command must be pnpm convex:deploy:vercel. That script runs npx convex deploy --cmd 'pnpm build' --cmd-url-env-var-name VITE_CONVEX_URL, so Convex deploys from the same commit and injects VITE_CONVEX_URL into the Vite build.

See references/env-mapping.md for the full canonical list of which var lives where and why. </stack_context>

<critical_safety> 🛑 NEVER run vercel --prod or vercel deploy --prod until step 03. The first deploy must happen AFTER vercel.json and Vercel env vars are in place, otherwise Vercel will deploy a broken build and the user has to roll back.

🛑 NEVER write secrets to git-tracked files. No secrets in vercel.json, package.json, CHANGELOG.md, or any committed file.

🛑 NEVER vercel env add app/runtime variables such as STRIPE_*, RESEND_*, R2_*, OAuth secrets, or VITE_EMAIL_CONTACT. Those belong in Convex or static app config, not Vercel.

🛑 NEVER reuse the dev Convex deployment as production. A fresh convex deployment create --prod (or first convex deploy) creates the prod deployment. Conflating dev and prod data is unrecoverable. </critical_safety>

<success_metrics> ✅ A https://{prod_domain} URL responds with a working app ✅ Sign up / sign in works end-to-end (Better Auth + Resend email delivery) ✅ Stripe checkout and webhook end-to-end work ✅ npx convex env list --prod returns every var listed in references/env-mapping.md (Convex column), with STRIPE_WEBHOOK_SECRET added after the Stripe webhook exists ✅ vercel env ls returns only the Vercel deploy keys listed in references/env-mapping.md ✅ git push to the production branch automatically triggers pnpm convex:deploy:vercel on Vercel ✅ CHANGELOG.md has a FEATURE: entry for the production launch </success_metrics>

<failure*modes> ❌ Setting STRIPE_WEBHOOK_SECRET only in Vercel. The webhook route is convex/http.ts, so the signing secret must live in Convex prod env ❌ Forgetting CONVEX_DEPLOY_KEY in Vercel - the build will fail because npx convex deploy has no auth ❌ Forgetting CONVEX_PROD_DEPLOY_KEY in Vercel Preview - preview builds cannot import a production snapshot ❌ Setting SITE_URL to the Vercel auto-URL (*.vercel.app) instead of the custom prod domain - OAuth and email links will break ❌ Not adding https://{prod_url}/api/auth/callback/{provider} to GitHub/Google OAuth apps - users get OAuth callback errors ❌ Leaving EMAIL_FROM set to onboarding@resend.dev in prod - Resend will silently drop emails to non-test recipients ❌ Setting test-mode Stripe keys in production (sk_test* and pk_*test*) - real users cannot pay ❌ Modifying .env for prod values - this file is local-only; production env lives in Convex / Vercel </failure_modes>

NEXT STEP

Load steps/step-00-init.md.