Update to Vercel

{
  "name": "env-vars",
  "description": "Vercel environment variable expert guidance. Use when working with .env files, vercel env commands, OIDC tokens, or managing environment-specific configuration.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 105
    }
  ],
  "skill_md_contents": "---\nname: env-vars\ndescription: Vercel environment variable expert guidance. Use when working with .env files, vercel env commands, OIDC tokens, or managing environment-specific configuration.\nmetadata:\n  priority: 7\n  docs:\n    - \"https://vercel.com/docs/environment-variables\"\n  sitemap: \"https://vercel.com/sitemap/docs.xml\"\n  pathPatterns:\n    - '.env'\n    - '.env.*'\n    - '.env.local'\n    - '.env.production'\n    - '.env.development'\n    - '.env.test'\n    - '.env.production.local'\n    - '.env.development.local'\n    - '.env.test.local'\n    - '.env.example'\n  bashPatterns:\n    - '\\bvercel\\s+env\\s+pull\\b'\n    - '\\bvercel\\s+env\\s+add\\b'\n    - '\\bvercel\\s+env\\s+rm\\b'\n    - '\\bvercel\\s+env\\s+ls\\b'\n---\n\n# Vercel Environment Variables\n\nYou are an expert in Vercel environment variable management — `.env` file conventions, the `vercel env` CLI, OIDC token lifecycle, and environment-specific configuration.\n\n## .env File Hierarchy\n\nVercel and Next.js load environment variables in a specific order. Later files override earlier ones:\n\n| File | Purpose | Git-tracked? |\n|------|---------|-------------|\n| `.env` | Default values for all environments | Yes |\n| `.env.local` | Local overrides and secrets | **No** (gitignored) |\n| `.env.development` | Development-specific defaults | Yes |\n| `.env.development.local` | Local dev overrides | **No** |\n| `.env.production` | Production-specific defaults | Yes |\n| `.env.production.local` | Local prod overrides | **No** |\n| `.env.test` | Test-specific defaults | Yes |\n| `.env.test.local` | Local test overrides | **No** |\n\n### Load Order (Next.js)\n\n1. `.env` (lowest priority)\n2. `.env.[environment]` (development, production, or test)\n3. `.env.local` (skipped in test environment)\n4. `.env.[environment].local` (highest priority, skipped in test)\n\n### Critical Rules\n\n- **Never commit secrets** to `.env`, `.env.development`, or `.env.production` — use `.local` variants or Vercel environment variables\n- `.env.local` is always gitignored by Next.js — this is where `vercel env pull` writes secrets\n- Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser bundle — never put secrets in `NEXT_PUBLIC_` vars\n- All other variables are server-only (API routes, Server Components, middleware)\n\n## vercel env CLI\n\n### Pull Environment Variables\n\n```bash\n# Pull all env vars for the current environment into .env.local\nvercel env pull .env.local\n\n# Pull for a specific environment\nvercel env pull .env.local --environment=production\nvercel env pull .env.local --environment=preview\nvercel env pull .env.local --environment=development\n\n# Overwrite existing file without prompting\nvercel env pull .env.local --yes\n\n# Pull to a custom file\nvercel env pull .env.production.local --environment=production\n```\n\n### Add Environment Variables\n\n```bash\n# Interactive — prompts for value and environments\nvercel env add MY_SECRET\n\n# Non-interactive\necho \"secret-value\" | vercel env add MY_SECRET production\n\n# Add to multiple environments\necho \"secret-value\" | vercel env add MY_SECRET production preview development\n\n# Add a sensitive variable (encrypted, not shown in logs)\nvercel env add MY_SECRET --sensitive\n```\n\n### List Environment Variables\n\n```bash\n# List all environment variables\nvercel env ls\n\n# Filter by environment\nvercel env ls production\n```\n\n### Remove Environment Variables\n\n```bash\n# Remove from specific environment\nvercel env rm MY_SECRET production\n\n# Remove from all environments\nvercel env rm MY_SECRET\n```\n\n## Bootstrap Flow (Fresh Clone / New Machine)\n\nUse this sequence when setting up a project from scratch:\n\n```bash\n# 1) Link first so pulls target the correct Vercel project\nvercel link --yes --project <name-or-id> --scope <team>\n\n# 2) Pull env vars into .env.local\nvercel env pull .env.local --yes\n\n# 3) Verify required keys from .env.example exist in .env.local\nwhile IFS='=' read -r key _; do\n  [[ -z \"$key\" || \"$key\" == \\#* ]] && continue\n  grep -q \"^${key}=\" .env.local || echo \"Missing in .env.local: $key\"\ndone < .env.example\n```\n\n### Temporary Path: Run With Vercel Envs Without Writing a File\n\nIf you need Vercel environment variables immediately but do not want to write `.env.local` yet:\n\n```bash\nvercel env run -- npm run dev\n```\n\nThis is useful for quick validation during bootstrap, but still pull `.env.local` for a normal local workflow.\n\n### Re-pull After Secret or Provisioning Changes\n\nAfter creating/updating secrets (`vercel env add`, dashboard changes) or provisioning integrations that add env vars (for example Neon/Upstash), re-run:\n\n```bash\nvercel env pull .env.local --yes\n```\n\n## OIDC Token Lifecycle\n\nVercel uses **OIDC (OpenID Connect)** tokens for secure, keyless authentication between your app and Vercel services (AI Gateway, storage, etc.).\n\n### How It Works\n\n1. **On Vercel deployments**: `VERCEL_OIDC_TOKEN` is automatically injected as a short-lived JWT and auto-refreshed — zero configuration needed\n2. **Local development**: `vercel env pull .env.local` provisions a `VERCEL_OIDC_TOKEN` valid for ~12 hours\n3. **Token expiry**: When the local OIDC token expires, re-run `vercel env pull .env.local --yes` to get a fresh one. Consider re-pulling at the start of each dev session to avoid mid-session auth failures\n\n### Common OIDC Patterns\n\n```ts\n// The @vercel/oidc package reads VERCEL_OIDC_TOKEN automatically\nimport { getVercelOidcToken } from '@vercel/oidc'\n\n// AI Gateway uses OIDC by default — no manual token handling needed\nimport { gateway } from 'ai'\nconst result = await generateText({\n  model: gateway('openai/gpt-5.2'),\n  prompt: 'Hello',\n})\n```\n\n### Troubleshooting OIDC\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `VERCEL_OIDC_TOKEN` missing locally | Haven't pulled env vars | `vercel env pull .env.local` |\n| Auth errors after ~12h locally | Token expired | `vercel env pull .env.local --yes` |\n| Works on Vercel, fails locally | Token not in `.env.local` | `vercel env pull .env.local` |\n| `AI_GATEWAY_API_KEY` vs OIDC | Both set, key takes priority | Remove `AI_GATEWAY_API_KEY` to use OIDC |\n\n## Environment-Specific Configuration\n\n### Vercel Dashboard vs .env Files\n\n| Use Case | Where to Set |\n|----------|-------------|\n| Secrets (API keys, tokens) | Vercel Dashboard (`https://vercel.com/{team}/{project}/settings/environment-variables`) or `vercel env add` |\n| Public config (site URL, feature flags) | `.env` or `.env.[environment]` files |\n| Local-only overrides | `.env.local` |\n| CI/CD secrets | Vercel Dashboard (`https://vercel.com/{team}/{project}/settings/environment-variables`) with environment scoping |\n\n### Environment Scoping on Vercel\n\nVariables set in the Vercel Dashboard at `https://vercel.com/{team}/{project}/settings/environment-variables` can be scoped to:\n\n- **Production** — only `vercel.app` production deployments\n- **Preview** — branch/PR deployments\n- **Development** — `vercel dev` and `vercel env pull`\n\nA variable can be assigned to one, two, or all three environments.\n\n### Git Branch Overrides\n\nPreview environment variables can be scoped to specific Git branches:\n\n```bash\n# Add a variable only for the \"staging\" branch\necho \"staging-value\" | vercel env add DATABASE_URL preview --git-branch=staging\n```\n\n## Gotchas\n\n### `vercel env pull` Overwrites Custom Variables\n\n`vercel env pull .env.local` **replaces the entire file** — any manually added variables (custom secrets, local overrides, debug flags) are lost. Always back up or re-add custom vars after pulling:\n\n```bash\n# Save custom vars before pulling\ngrep -v '^#' .env.local | grep -v '^VERCEL_\\|^POSTGRES_\\|^NEXT_PUBLIC_' > .env.custom.bak\nvercel env pull .env.local --yes\ncat .env.custom.bak >> .env.local  # Re-append custom vars\n```\n\nOr maintain custom vars in a separate `.env.development.local` file (loaded after `.env.local` by Next.js).\n\n### Scripts Don't Auto-Load `.env.local`\n\nOnly Next.js auto-loads `.env.local`. Standalone scripts (`drizzle-kit`, `tsx`, custom Node scripts) need explicit loading:\n\n```bash\n# Use dotenv-cli\nnpm install -D dotenv-cli\nnpx dotenv -e .env.local -- npx drizzle-kit push\nnpx dotenv -e .env.local -- npx tsx scripts/seed.ts\n\n# Or source manually\nsource <(grep -v '^#' .env.local | sed 's/^/export /') && node scripts/migrate.js\n```\n\n## Best Practices\n\n1. **Use `vercel env pull` as part of your setup workflow** — document it in your README\n2. **Never hardcode secrets** — always use environment variables\n3. **Scope narrowly** — don't give preview deployments production database access\n4. **Rotate OIDC tokens regularly in local dev** — re-pull when you see auth errors\n5. **Use `.env.example`** — commit a template with empty values so teammates know which vars are needed\n6. **Prefix client-side vars with `NEXT_PUBLIC_`** — and never put secrets in them\n7. **Keep custom vars in `.env.development.local`** — protects them from `vercel env pull` overwrites\n\n## Official Documentation\n\n- [Environment Variables](https://vercel.com/docs/environment-variables)\n- [Vercel CLI: env](https://vercel.com/docs/cli/env)\n- [Next.js Environment Variables](https://nextjs.org/docs/app/building-your-application/configuring/environment-variables)\n"
}