docs: clarify .env/.env.local convention (#2158)

Author: abumoaz1

.env

@@ -1,9 +1,6 @@
-# Environment variables
-# https://vitejs.dev/guide/env-and-mode.html#env-files
-#
-# TIP: Feel free to personalize these settings in your `.env.local` file that
-#      is not tracked by source control, giving you the liberty to tweak
-#      settings in your local environment worry-free! Happy coding! 🚀
+# Shared environment defaults committed to git (no real secrets).
+# Put real credentials in `.env.local` (git-ignored), which overrides `.env`.
+# https://vite.dev/guide/env-and-mode#env-files
 
 # Web application settings
 APP_NAME=Acme Co.

.gitignore

@@ -22,6 +22,7 @@ node_modules/
 *.lcov
 
 # Environment variables
+# `.env` is committed with shared defaults/placeholders; keep secrets in `.env.local`.
 .env.*.local
 .env.local
 
@@ -69,4 +70,3 @@ srcpack.config.ts
 # macOS
 # https://github.com/github/gitignore/blob/master/Global/macOS.gitignore
 .DS_Store
-

README.md

@@ -83,7 +83,17 @@ bun install
 
 ### 3. Configure Environment
 
-Update environment variables in [`.env`](./.env) and `.env.local` files as well as Wrangler configuration in [`wrangler.jsonc`](./apps/api/wrangler.jsonc).
+This project follows [Vite env conventions](https://vite.dev/guide/env-and-mode#env-files):
+
+- [`.env`](./.env) is committed and contains shared defaults/placeholders only (no real secrets)
+- `.env.local` is git-ignored and should contain your real credentials
+- `.env.local` values override `.env`
+
+```bash
+cp .env .env.local  # then replace placeholder values with real ones
+```
+
+Also check [`wrangler.jsonc`](./apps/api/wrangler.jsonc) for Worker configuration and bindings.
 
 ### 4. Start Development