Env and Config

Keep environment variables and configuration documented and consistent so the app runs correctly in every environment.

When to Activate

• User asks for ".env.example", "env documentation", or "what env vars are needed"
• Adding a new service or feature that requires config
• Onboarding: documenting required and optional settings
• Setting up a new environment (dev, staging, CI)
• Validating config at startup (e.g. Zod, joi) and aligning docs

Work Process

1. Discover what the app reads — Search codebase for env access: process.env, os.environ, env(), config modules, and any loaded config files. List every variable name and where it is used.
2. Classify — Required vs optional; defaults (in code or doc); which env it applies to (all, prod-only, dev-only). Note secrets (never put real values in .env.example or repo).
3. Create or update .env.example — One line per variable: name, example/placeholder value, comment (purpose, required/optional, example). Use same names as in code. No real secrets.
4. Document — In README or config doc: table or list of variables, required/optional, defaults, and where used (e.g. "Auth", "DB"). Link from README to .env.example or config doc.
5. Align with validation — If the app validates env at startup (e.g. Zod schema), ensure .env.example includes all required vars and types so a copy-paste runs (with placeholders). Document any new vars in the same PR as the feature.