Add Vercel deployment path and clarify Supabase env errors

From the PR description

Summary

Prepare Gary for a simple one-person deployment on Vercel (with Supabase for database/auth and future Clerk login). Documentation + a clearer missing-env error. No product features, no Clerk, no database migration, no Cloudflare changes.

Deployment architecture (audit result)

Gary's frontend is a Next.js app (frontend/) that talks to a separate Express backend (backend/) over NEXT_PUBLIC_API_BASE_URL. The backend needs LibreOffice, multer file uploads, and a long-running process - a poor fit for Vercel serverless. So:

• Vercel hosts: the Next.js frontend only (frontend/).
• Backend stays separate: deploy on Railway / Render / Fly.io / a VM - not Vercel.
• Supabase: Postgres database + authentication.
• Object storage: S3-compatible bucket (e.g. Cloudflare R2), used by the backend.

Files changed

• docs/VERCEL_DEPLOYMENT.md (new) - plain-English guide: overview + architecture diagram, what Vercel hosts, what Supabase handles, why the backend stays separate, required public vs private env vars, the public-vs-private secret rule, GitHub import steps, Vercel project settings, preview deployments, custom domain, troubleshooting, and a "Future Clerk login" section.
• frontend/.env.vercel.example (new) - public NEXT_PUBLIC_* values clearly separated from server-side secrets, with explicit warnings never to put provider / Supabase service-role / database / JWT / Clerk secret keys in NEXT_PUBLIC_*. Includes a clearly-labeled future-only Clerk section (commented out).
• frontend/src/lib/supabase.ts - replaces the cryptic supabaseUrl is required failure with a clear message naming the missing variable and where to set it. Also accepts the standard NEXT_PUBLIC_SUPABASE_ANON_KEY name, falling back to the legacy NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY so existing deployments keep working. Runtime safety unchanged - missing config still throws.
• frontend/src/lib/auth.ts - same NEXT_PUBLIC_SUPABASE_ANON_KEY fallback; returns null cleanly with a named-variable log if config is missing.
• README.md - brief "Deploying Gary on Vercel" section + docs link.
• docs/README.md - links the new Vercel guide.
• .gitignore - allow .env.vercel.example to be committed.

Recommended Vercel settings

No vercel.json and no build:vercel script were added - they would add nothing over Vercel's defaults once Root Directory is frontend. The existing Cloudflare files (open-next.config.ts, preview/deploy scripts) are untouched and do not interfere with next build.

Environment variables

Public (browser-safe, set in Vercel):

• NEXT_PUBLIC_SITE_URL
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY (legacy NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY still accepted)
• NEXT_PUBLIC_API_BASE_URL (the separate backend's public URL)

Private (server-side secrets - live on the backend host, never NEXT_PUBLIC_): OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, SUPABASE_SERVICE_ROLE_KEY, DOWNLOAD_SIGNING_SECRET, USER_API_KEYS_ENCRYPTION_SECRET, R2_*, RESEND_API_KEY. Future-only: CLERK_SECRET_KEY.

Supabase error message - improved

Yes. The prerender failure previously surfaced as the raw supabaseUrl is required. It now reads:

Missing NEXT_PUBLIC_SUPABASE_URL. Add it in Vercel Project Settings → Environment Variables (or in frontend/.env.local for local development).

(and the equivalent for NEXT_PUBLIC_SUPABASE_ANON_KEY). No real credentials hardcoded; missing config still throws.

Validation

• Backend: bun run build - clean.
• Frontend: bun run build - TypeScript compilation succeeds (Compiled successfully in 25.2s, Finished TypeScript in 16.7s). The static prerender of /account/models still fails - now with the improved message Missing NEXT_PUBLIC_SUPABASE_URL... instead of supabaseUrl is required. This is expected in this codespace because no Supabase env vars are set; on Vercel with the four public variables configured, the build completes. Required to build: NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY.
• Frontend tests: branding, exportDraft, matterReviewTable, builtinWorkflows - all pass.
• Lint: error count unchanged (43, all pre-existing); the changed files add no new issues.

Backend remains separate

Yes - confirmed and documented. The backend is not deployed to Vercel in this path.

Recommended next PR

• Add Clerk authentication so a Vercel deployment can be safely access-restricted (the guide already explains why an unprotected deployment should not hold real client data).
• Optionally provide a one-click backend deploy template (Railway/Render) so the separate-backend step is as easy as the Vercel step.

Test plan

• Import the repo into Vercel, set Root Directory to frontend, add the four public env vars → build succeeds.
• Omit NEXT_PUBLIC_SUPABASE_URL → build fails with the clear named-variable message.
• App loads and reaches the backend via NEXT_PUBLIC_API_BASE_URL.
• Existing deployments using NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY still work.

https://claude.ai/code/session_01LNzU9cGoR4SsYXon8H7aJZ

Generated by Claude Code