docs: clarify .env scope for env separation (#39)

* docs: clarify .env is for CLI only, not deployed endpoint env

Update all documentation to reflect env separation:
- .env populates os.environ for CLI and local dev
- Resource env={} is the explicit way to set endpoint env vars
- flash login is the primary auth method
- Deploy-time preview shows what goes to each endpoint

* docs: address PR review feedback on env var examples

- Use os.getenv() instead of os.environ[] in doc examples
- Show both uv run and bare flash login invocations
- Split dense paragraph into scannable bullets in CONTRIBUTING.md

* docs: standardize os.environ for deploy-time env examples

- Use os.environ["KEY"] consistently across all files (loud KeyError
  on missing vars is better UX than silently passing None via getenv)
- Convert CONTRIBUTING.md bullets to blockquote callout
- Fix duplicate step numbering in troubleshooting.md

Author: deanq

CLI-REFERENCE.md

@@ -839,12 +839,14 @@ export FLASH_PORT=9000
 
 **.env file:**
 ```bash
-# .env (loaded automatically by Flash)
+# .env (loaded into os.environ for CLI and local development)
 RUNPOD_API_KEY=your-key-here
 FLASH_HOST=0.0.0.0
 FLASH_PORT=8888
 ```
 
+> **Note:** `.env` values populate `os.environ` locally. They are **not** carried to deployed endpoints. To pass env vars at deploy time, declare them on the resource: `env={"KEY": os.environ["KEY"]}`.
+
 ## Configuration Files
 
 Flash uses these configuration files:

CONTRIBUTING.md

@@ -332,7 +332,11 @@ To debug a worker:
 4. Choose the appropriate debug configuration
 5. The debugger will execute the `if __name__ == "__main__"` test block
 
-The `.env` file is automatically loaded, so your `RUNPOD_API_KEY` is available during debugging.
+The `.env` file is loaded into `os.environ` for local CLI use and debugging.
+
+> To pass environment variables to deployed endpoints, declare them explicitly on the resource config, for example: `env={"KEY": os.environ["KEY"]}`.
+>
+> For authentication, prefer using `flash login`.
 
 ### Unit Tests (Recommended)
 

docs/cli/commands.md

@@ -329,15 +329,17 @@ This hybrid approach enables rapid development: iterate on your orchestration lo
 
 ### Environment Variables
 
-Variables can be set in `.env` file or exported in shell:
+Variables can be set in `.env` file or exported in shell. The `.env` file populates `os.environ` for local CLI use and development -- it is not carried to deployed endpoints.
 
 ```bash
-# .env file
+# .env file (local CLI and development only)
 FLASH_HOST=0.0.0.0
 FLASH_PORT=9000
 RUNPOD_API_KEY=your-key-here
 ```
 
+> To pass env vars to deployed endpoints, declare them on the resource config: `env={"HF_TOKEN": os.environ["HF_TOKEN"]}`.
+
 **Precedence (highest to lowest):**
 1. Command-line options (`--host`, `--port`)
 2. Environment variables (`FLASH_HOST`, `FLASH_PORT`)

docs/cli/getting-started.md

@@ -27,10 +27,10 @@ uv run flash login
 
 This opens a browser for authentication and saves your credentials.
 
-**Alternative:** Set your Runpod API key manually:
+**Alternative:** Set your Runpod API key in the environment for local CLI use:
 ```bash
 export RUNPOD_API_KEY=your-key-here
-# Or add to .env file:
+# Or add to .env file (populates os.environ locally, not carried to deployed endpoints):
 echo "RUNPOD_API_KEY=your-key-here" > .env
 ```
 

docs/cli/troubleshooting.md

@@ -659,28 +659,37 @@ Error: RUNPOD_API_KEY environment variable not set
 
 **Solutions:**
 
-**1. Set environment variable:**
+**1. Use `flash login` (recommended):**
+```bash
+# If you installed Flash via uv (recommended)
+uv run flash login
+
+# Or, if flash is installed globally
+flash login
+```
+
+**2. Set environment variable:**
 ```bash
 export RUNPOD_API_KEY=your-key-here
 
 # Verify
 echo $RUNPOD_API_KEY
 ```
 
-**2. Add to .env file:**
+**3. Add to .env file (for local CLI use):**
 ```bash
 echo "RUNPOD_API_KEY=your-key-here" >> .env
 
-# Flash automatically loads .env
+# Loaded into os.environ for CLI commands
 ```
 
-**3. Get API key:**
+**4. Get API key:**
 1. Visit https://runpod.io/console/user/settings
 2. Click "API Keys"
 3. Create new key or copy existing
 4. Set environment variable
 
-**4. Make persistent (bash/zsh):**
+**5. Make persistent (bash/zsh):**
 ```bash
 echo 'export RUNPOD_API_KEY=your-key-here' >> ~/.bashrc
 source ~/.bashrc
@@ -1046,12 +1055,12 @@ export RUNPOD_API_KEY=your-key
 flash deploy
 ```
 
-**3. Use .env file:**
+**3. Use .env file (for local CLI use):**
 ```bash
 # Create .env in project root
 echo "RUNPOD_API_KEY=your-key" > .env
 
-# Flash automatically loads .env
+# Loaded into os.environ for CLI commands
 flash deploy
 ```
 
@@ -1078,18 +1087,23 @@ ERROR: Authentication failed: API key expired
 
 **Solutions:**
 
-**1. Generate new key:**
+**1. Re-authenticate with `flash login` (recommended):**
+```bash
+flash login
+```
+
+**2. Or generate a new key manually:**
 1. Visit https://runpod.io/console/user/settings
 2. Revoke expired key
 3. Create new key
-4. Update environment variable
+4. Update environment variable or `.env` file
 
-**2. Update in all locations:**
+**3. Update in all locations:**
 ```bash
 # Update environment variable
 export RUNPOD_API_KEY=new-key
 
-# Update .env file
+# Or update .env file (for local CLI use)
 echo "RUNPOD_API_KEY=new-key" > .env
 
 # Update CI/CD secrets

docs/cli/workflows.md

@@ -63,24 +63,25 @@ python --version  # Should show 3.10+
 uv run flash --version  # Should show flash version
 ```
 
-#### 3. Configure Environment Variables
+#### 3. Authenticate
 
-```bash
-# Copy example environment file
-cp .env.example .env
+The recommended way to authenticate is `flash login`:
 
-# Edit .env file
-# Required: RUNPOD_API_KEY (for deployment)
-# Optional: FLASH_HOST, FLASH_PORT (for development)
+```bash
+uv run flash login
 ```
 
-Example `.env`:
+Alternatively, set `RUNPOD_API_KEY` in your environment or a `.env` file for local CLI use:
+
 ```bash
+# .env file (populates os.environ for CLI and local development)
 RUNPOD_API_KEY=your-key-here
 FLASH_HOST=localhost
 FLASH_PORT=8888
 ```
 
+> **Note:** `.env` values are **not** carried to deployed endpoints. To pass env vars at deploy time, declare them on the resource: `env={"KEY": os.environ["KEY"]}`.
+
 #### 4. Start Development Server
 
 ```bash