Change frontend .env files to be committed and have .env.*.local overrides (#6207)

AGENTS.md

@@ -136,12 +136,14 @@ The project structure is defined in `engine/pyproject.toml`. Any new dependencie
   - **Development**: `task desktop:dev` for desktop dev mode
 
 #### Environment Variables
-- All `VITE_*` variables must be declared in the appropriate example file:
-  - `frontend/config/.env.example` — core, proprietary, and shared vars
-  - `frontend/config/.env.saas.example` — SaaS-only vars
-  - `frontend/config/.env.desktop.example` — desktop (Tauri)-only vars
-- Never use `|| 'hardcoded-fallback'` inline — put defaults in the example files
-- `task frontend:prepare` / `prepare:saas` / `prepare:desktop` auto-create the env files from examples on first run, and error if any required keys are missing
+- All `VITE_*` variables must be declared in the appropriate committed env file:
+  - `frontend/.env` — core, proprietary, and shared vars
+  - `frontend/.env.saas` — SaaS-only vars (layered on top of `.env` in SaaS mode)
+  - `frontend/.env.desktop` — desktop (Tauri)-only vars (layered on top of `.env` in desktop mode)
+- These files are committed to Git and must not contain private keys
+- Local overrides (API keys, machine-specific settings) go in uncommitted sibling `.env.local` / `.env.saas.local` / `.env.desktop.local` files — Vite automatically layers them on top
+- Never use `|| 'hardcoded-fallback'` inline — put defaults in the committed env files
+- `task frontend:prepare` / `prepare:saas` / `prepare:desktop` create empty `.local` override files on first run
 - Prepare runs automatically as a dependency of all `dev*`, `build*`, and `desktop*` tasks
 - See `frontend/README.md#environment-variables` for full documentation