docs(env): Reconcile .env.example with variables actually read

[jeromehardaway]

Problem

.env.example had drifted from what the app actually reads: it advertised variables no code consumes, and omitted variables that API routes, configs, and generator scripts require. Nothing indicated which values are required vs optional, secret vs public, or where they are consumed.

Solution

Audited every process.env read (including dynamic process.env[name] in src/pages/api/health.ts and env("DATABASE_URL") in prisma/schema.prisma) across src/, repo-root scripts/, prisma/, next.config.js, next-sitemap.config.js, playwright.config.ts, vitest.config.mts, and postcss.config.js, then rewrote .env.example to match. Each variable is grouped by subsystem and annotated with required/optional, secret/public, and consuming file(s).

Added (read by code, previously missing):

• CLOUDINARY_CLOUD_NAME — src/pages/api/lms/progress/index.ts, src/pages/api/lms/certificates/generate.ts (read without the NEXT_PUBLIC_ prefix)
• MAILCHIMP_API_KEY, MAILCHIMP_LIST_ID — src/pages/api/newsletter.ts
• CONTACT_WEBHOOK_ID, APPLY_WEBHOOK_ID, MENTOR_WEBHOOK_ID — Slack webhooks for src/pages/api/{contact,apply,mentor,mentee}.ts
• NEXT_PUBLIC_GOOGLE_ANALYTICS_ID — src/pages/_document.tsx
• NEXT_PUBLIC_SITE_URL — next-sitemap.config.js
• GOOGLE_PRIVATE_KEY — legacy-named fallback Gemini key in scripts/generate-*.ts
• TECH_PATHWAYS_MODEL — scripts/generate-tech-pathways.ts

Removed (grep across the repo proves no code reads them):

• LMS_DEV_BYPASS — only occurrence was .env.example itself
• GITHUB_PAT — code only reads GITHUB_TOKEN (src/lib/git-api-client.ts)
• SHOPIFY_ADMIN_ACCESS_TOKEN — referenced in docs only; no code reads it
• Commented GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — no Google OAuth provider is configured

NODE_ENV and CI are read but tooling-set, so they are documented in the header rather than listed as settable values. A zod runtime env validator was considered and skipped as out of scope (possible follow-up).

Verification

• npm test — 41 files, 384 tests, all pass
• npm run typecheck — same 4 pre-existing errors in __tests__/pages/api/j0di3/{learning,troops}.test.ts on both clean master and this branch; none introduced
• npm run lint — same 20 pre-existing errors in untouched test files on both clean master and this branch; .env.example is not linted
• No build needed: content-only change to .env.example

Follow-up note: AGENTS.md and docs/SHOPIFY_SETUP.md still mention LMS_DEV_BYPASS, GITHUB_PAT, and SHOPIFY_ADMIN_ACCESS_TOKEN; updating those docs is outside this issue's scope.

Closes #1063

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vets-who-code-app	Ready	Preview, Comment	Jun 11, 2026 4:43pm