docs: add .env to directory structure and improve config docs (#18594)

docs/2.guide/2.directory-structure/2.env.md

@@ -0,0 +1,38 @@
+---
+navigation.icon: IconFile
+title: ".env"
+description: "A .env file specifies your build/dev-time environment variables."
+head.title: ".env"
+---
+
+# .env File
+
+Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support in development mode and when running `nuxi build` and `nuxi generate`.
+
+In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded **at build, dev, and generate time**, and any environment variables set there will be accessible within your `nuxt.config` file and modules.
+
+::alert
+If you want to use a different file - for example, to use `.env.local` or `.env.production` - you can do so by passing the `--dotenv` flag when using `nuxi`. For example:
+
+```bash
+npx nuxi dev --dotenv .env.local
+```
+
+Just as above, this will only apply in development mode and when running `nuxi build` and `nuxi generate`.
+::
+
+When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.
+
+::alert{type=warning}
+Note that removing a variable from `.env` or removing the `.env` file entirely will not unset values that have already been set.
+::
+
+However, **after your server is built**, you are responsible for setting environment variables when you run the server. Your `.env` file will not be read at this point. How you do this is different for every environment. On a Linux server, you could pass the environment variables as arguments using the terminal `DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`. Or you could source your env file using `source .env && node .output/server/index.mjs`.
+
+Note that for a purely static site, it is not possible to set runtime configuration config after your project is prerendered.
+
+:ReadMore{link="/docs/guide/going-further/runtime-config"}
+
+If you want to use environment variables set at build time but do not care about updating these down the line (or only need to update them reactively _within_ your app) then `appConfig` may be a better choice. You can define `appConfig` both within your `nuxt.config` (using environment variables) and also within an `~/app.config.ts` file in your project.
+
+:ReadMore{link="/docs/guide/directory-structure/app-config"}

docs/2.guide/3.going-further/10.runtime-config.md

@@ -49,21 +49,19 @@ Instead of passing non-serializable objects or functions into your application f
 
 The most common way to provide configuration is by using [Environment Variables](https://medium.com/chingu/an-introduction-to-environment-variables-and-how-to-use-them-f602f66d15fa).
 
-::alert{type=info}
-Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support in development mode and when running `nuxi build` and `nuxi generate`.
+::alert{type=warning}
+Nuxi CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your `.env` file will not be read**.
 
-In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded **at build, dev, and generate time**, and any environment variables set there will be accessible within your `nuxt.config` file and modules.
-
-When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.
-
-However, **after your server is built**, you are responsible for setting environment variables when you run the server. Your `.env` file will not be read at this point. How you do this is different for every environment. On a Linux server, you could pass the environment variables as arguments using the terminal `DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`. Or you could source your env file using `source .env && node .output/server/index.mjs`.
-
-Note that for a purely static site, it is not possible to set runtime configuration config after your project is prerendered.
+:ReadMore{link="/docs/guide/directory-structure/env"}
 ::
 
-Runtime config values are automatically replaced by matching environment variables at runtime. For this to work, you _must_ have a fallback value (which can just be an empty string) defined in your `nuxt.config`.
+Runtime config values are automatically replaced by matching environment variables at runtime. There are two key requirements.
 
-**Example:**
+1. Your desired variables must be defined in your `nuxt.config`. This ensures that arbitrary environment variables are not exposed to your application code.
+
+1. Only a specially-named environment variable can override a runtime config property. That is, an uppercase environment variable starting with `NUXT_` which uses `_` to separate keys and case changes.
+
+#### Example
 
 ```sh [.env]
 NUXT_API_SECRET=api_secret_token