Document the new .env support for local development

Author: petebacondarwin

src/content/docs/workers/configuration/environment-variables.mdx

@@ -95,6 +95,8 @@ Select the **Secret** type if your environment variable is a [secret](/workers/c
 
 <Render file="env_and_secrets" />
 
+### Local development with secrets
+
 <Render file="secrets-in-dev" />
 
 ## Related resources

src/content/partials/workers/secrets-in-dev.mdx

@@ -2,15 +2,26 @@
 {}
 ---
 
-When developing your Worker or Pages Function, create a `.dev.vars` file in the root of your project to define secrets that will be used when running `wrangler dev` or `wrangler pages dev`, as opposed to using environment variables in the [Wrangler configuration file](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables). This works both in local and remote development modes.
+To define variables to use in local development that you do not want to store in Wrangler config (for example secrets that are defined for production deployment in [Wrangler configuration file](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables)), create either a `.dev.vars` file, or a `.env` file in the root of your project.
+You should use either `.dev.vars` or `.env` but not both. If you define a `.dev.vars` file, then values in `.env` files will be ignored for local development.
 
-The `.dev.vars` file should be formatted like a `dotenv` file, such as `KEY="VALUE"`:
+The `.dev.vars` and `.env` files should be formatted using the `dotenv` syntax, such as `KEY="VALUE"`:
 
-```bash title=".dev.vars"
+```bash title=".dev.vars / .env"
 SECRET_KEY="value"
 API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
 ```
 
-To set different secrets for each environment, create files named `.dev.vars.<environment-name>`. When you use `wrangler <command> --env <environment-name>`, the corresponding environment-specific file will be loaded instead of the `.dev.vars` file.
+To set different secrets for each Cloudflare environment, create files named `.dev.vars.<environment-name>` or `.env.<environment-name>`.
+When you select a Cloudflare environment in your local development, the corresponding environment-specific file will be loaded ahead of the generic `.dev.vars` (or `.env`) file.
 
-Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.
+- When using `.dev.vars.<environment-name>` files, all secrets must be defined per environment. If `.dev.vars.<environment-name>` exists then only this will be loaded; the `.dev.vars` file will not be loaded.
+- In contrast, all matching `.env` files are loaded and the values are merged. For each variable, the value from the most specific file is used, with the following precedence:
+  - `.env.<environment-name>.local` (most specific)
+  - `.env.local`
+  - `.env.<environment-name>`
+  - `.env` (least specific)
+
+:::note
+To include every environment variable defined in your system's process environment as a local development variable, ensure there is no `.dev.vars` and then set the `CLOUDFLARE_INCLUDE_PROCESS_ENV` environment variable to `true`.
+:::