Environment setup is documented

Undocumented environment variables force every new developer to grep the codebase for process.env.* references and guess at formats, values, and provisioning steps. Missing variables cause silent failures at runtime (databases not connecting, API calls 401ing, features toggling off) that waste hours of debugging. For production deploys, an incomplete .env.example is a common cause of broken releases when a required variable is forgotten in the deploy pipeline's secrets store.

Create .env.example at the project root, list every variable referenced in code (process.env.*, import.meta.env.*), and comment each with its purpose and where to obtain the value. Reference the file from the README setup section. Example:

# PostgreSQL connection string
# Format: postgresql://user:password@host:port/database
DATABASE_URL=

# OpenAI API key from https://platform.openai.com/api-keys
OPENAI_API_KEY=

• ID: developer-documentation.getting-started.env-setup

• Severity: high

• What to look for: Check for a .env.example file (or .env.sample, .env.template) at the project root. If one exists, verify that every variable has a comment or description explaining what it is and where to get the value. Also check if the README references environment setup. Compare .env.example variables with actual .env references in the codebase (process.env., import.meta.env., etc.). Count all instances found and enumerate each.

• Pass criteria: A .env.example file exists with all required environment variables listed and documented with comments. The README mentions the .env setup step. Variables referenced in code (process.env.DATABASE_URL, etc.) are all present in .env.example. At least 1 implementation must be confirmed.

• Fail criteria: No .env.example exists but the project uses environment variables, or .env.example exists but is incomplete (missing variables that code references), or variables are listed without any description of what they are or where to get them.

• Skip (N/A) when: The project does not use any environment variables.

• Detail on fail: Example: "No .env.example file exists but codebase references 8 environment variables (OPENAI_API_KEY, DATABASE_URL, STRIPE_SECRET_KEY, etc.)" or ".env.example lists DATABASE_URL but doesn't explain the expected format or how to set up the database"

• Remediation: Create .env.example with descriptions:

  # Database connection string (PostgreSQL)
  # Format: postgresql://user:password@host:port/database
  DATABASE_URL=
  
  # OpenAI API key - get one at https://platform.openai.com/api-keys
  OPENAI_API_KEY=
  
  # Stripe secret key - find in Stripe Dashboard > Developers > API keys
  STRIPE_SECRET_KEY=