diff --git a/AGENTS.md b/AGENTS.md
index e64c479f2..3d5c1d3e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,7 +107,7 @@ The production server runs migrations during startup before serving traffic. Man
 
 ### Environment
 
-Copy `.env.example` to `.env`. The three required variables are:
+Copy `.env.example` to `.env.local`. The three required variables are:
 
 - `APP_URL` (default `http://localhost:3000`)
 - `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`)
diff --git a/docs/contributing/development.mdx b/docs/contributing/development.mdx
index 4207a8415..d3fa96ac9 100644
--- a/docs/contributing/development.mdx
+++ b/docs/contributing/development.mdx
@@ -57,8 +57,14 @@ This guide walks you through setting up Reactive Resume for local development. W
   </Step>
   
   <Step title="Configure Environment Variables">
-    Create a `.env` file in the project root:
-    
+    Copy `.env.example` to `.env.local` in the project root:
+
+    ```bash
+    cp .env.example .env.local
+    ```
+
+    Then edit `.env.local` as needed — for local development on the host, set at minimum:
+
     ```bash
     # Application
     PORT=3000
@@ -96,16 +102,16 @@ This guide walks you through setting up Reactive Resume for local development. W
   
   <Step title="Run Database Migrations If Needed">
     The server startup path runs migrations before serving traffic. To apply migrations manually without starting the app,
-    export `DATABASE_URL` because Drizzle Kit reads directly from `process.env`:
+    load `.env.local` with `dotenvx` because Drizzle Kit reads directly from `process.env`:
     
     ```bash
-    DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" pnpm run db:migrate
+    dotenvx run -f .env.local -- pnpm run db:migrate
     ```
   </Step>
   
   <Step title="Start the Development Server">
     ```bash
-    pnpm run dev
+    dotenvx run -f .env.local -- pnpm run dev
     ```
     
     Your local Reactive Resume instance will be available at [http://localhost:3000](http://localhost:3000).
@@ -122,7 +128,7 @@ Here are the most commonly used scripts during development:
 
 | Command                        | Description                                                 |
 | ------------------------------ | ----------------------------------------------------------- |
-| `pnpm dev`                     | Start the web and server development processes              |
+| `dotenvx run -f .env.local -- pnpm dev` | Start the web and server development processes   |
 | `pnpm build`                   | Build the production web bundle and server bundle           |
 | `pnpm start`                   | Start the built production server                           |
 | `pnpm typecheck`               | Run TypeScript type checking                                |
@@ -135,9 +141,9 @@ Here are the most commonly used scripts during development:
 
 | Command                | Description                                  |
 | ---------------------- | -------------------------------------------- |
-| `pnpm run db:generate` | Generate migration files from schema changes |
-| `pnpm run db:migrate`  | Apply pending migrations                     |
-| `pnpm run db:studio`   | Open Drizzle Studio (database GUI)           |
+| `dotenvx run -f .env.local -- pnpm run db:generate` | Generate migration files from schema changes |
+| `dotenvx run -f .env.local -- pnpm run db:migrate`  | Apply pending migrations                     |
+| `dotenvx run -f .env.local -- pnpm run db:studio`   | Open Drizzle Studio (database GUI)           |
 
 ### Internationalization
 
@@ -180,7 +186,7 @@ reactive-resume/
 Use Drizzle Studio to explore and manage your database:
 
 ```bash
-pnpm run db:studio
+dotenvx run -f .env.local -- pnpm run db:studio
 ```
 
 This opens a web-based GUI at [https://local.drizzle.studio](https://local.drizzle.studio).
@@ -190,11 +196,11 @@ This opens a web-based GUI at [https://local.drizzle.studio](https://local.drizz
 1. Edit the schema in `packages/db/src/schema/*`
 2. Generate a migration:
    ```bash
-   pnpm run db:generate
+   dotenvx run -f .env.local -- pnpm run db:generate
    ```
 3. Apply the migration:
    ```bash
-   pnpm run db:migrate
+   dotenvx run -f .env.local -- pnpm run db:migrate
    ```
 
 <Warning>Always review generated migrations before applying them, especially when working with existing data.</Warning>
@@ -268,7 +274,7 @@ pnpm run typecheck
 		The Vite web server uses `PORT` (default `3000`), and the Hono server uses `SERVER_PORT` (default `3001`).
 		Either stop the conflicting process or choose alternate ports:
 		```bash
-		PORT=3002 SERVER_PORT=3003 pnpm dev
+		PORT=3002 SERVER_PORT=3003 dotenvx run -f .env.local -- pnpm dev
 		```
 	</Accordion>
 
@@ -296,7 +302,7 @@ pnpm run typecheck
 	<Accordion title="Type errors after pulling changes">
 		The route tree may need regeneration. Run the dev server which auto-generates routes:
 		```bash
-		pnpm run dev
+		dotenvx run -f .env.local -- pnpm run dev
 		```
 		Or run type checking to see specific errors:
 		```bash