docs: clarify functionality of $env/* variables

packages/kit/src/types/synthetic/$env+dynamic+private.md

@@ -1,10 +1,44 @@
-This module provides access to runtime environment variables, as defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](https://svelte.dev/docs/kit/cli)), this is equivalent to `process.env`. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](https://svelte.dev/docs/kit/configuration#env) (if configured).
+This module provides access to environment variables set _dynamically_ at runtime and that are limited to _private_ access.
 
-This module cannot be imported into client-side code.
+|         | Runtime                                                                  | Buildtime                                                                |
+| ------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| Private | `$env/dynamic/private`                                                   | [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private) |
+| Public  | [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public) | [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public)   |
+
+Runtime environment variables are defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](https://svelte.dev/docs/kit/cli)), this is equivalent to `process.env`.
+
+**_Private_ access:**
+
+- This module (and [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private)) cannot be imported into client-side code.
+- Variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`) are **excluded**.
+- Variables that begin with [`config.kit.env.privatePrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to allow-all) are **included**.
+
+> [!NOTE] In `dev`, `$env/dynamic` includes environment variables from `.env`. In `prod`, this behavior will depend on your adapter.
+
+> [!NOTE] To get correct types, environment variables referenced in your code should be declared (for example in an `.env` file), even if they don't have a value until the app is deployed:
+>
+> ```env
+> MY_FEATURE_FLAG=
+> ```
+>
+> You can override `.env` values from the command line like so:
+>
+> ```sh
+> MY_FEATURE_FLAG="enabled" npm run dev
+> ```
+
+For example, suppose the runtime environment variables were set like this:
+
+```env
+ENVIRONMENT=production
+PUBLIC_BASE_URL=http://site.com
+```
+
+If the `publicPrefix` is set to `PUBLIC_` and the `privatePrefix` is not set (the default behaviour):
 
 ```ts
 import { env } from '$env/dynamic/private';
-console.log(env.DEPLOYMENT_SPECIFIC_VARIABLE);
-```
 
-> [!NOTE] In `dev`, `$env/dynamic` always includes environment variables from `.env`. In `prod`, this behavior will depend on your adapter.
+console.log(env.ENVIRONMENT); // => "production"
+console.log(env.PUBLIC_BASE_URL); // => undefined
+```

packages/kit/src/types/synthetic/$env+dynamic+public.md

@@ -1,8 +1,59 @@
-Similar to [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private), but only includes variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code.
+This module provides access to environment variables set _dynamically_ at runtime and that are _publicly_ accessible.
 
-Note that public dynamic environment variables must all be sent from the server to the client, causing larger network requests — when possible, use `$env/static/public` instead.
+|         | Runtime                                                                    | Buildtime                                                                |
+| ------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Private | [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private) | [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private) |
+| Public  | `$env/dynamic/public`                                                      | [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public)   |
+
+Runtime environment variables are defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](https://svelte.dev/docs/kit/cli)), this is equivalent to `process.env`.
+
+**_Public_ access:**
+
+- This module (and [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public)) _can_ be imported into client-side code.
+- **Only** variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`) are included.
+
+> [!NOTE] In `dev`, `$env/dynamic` includes environment variables from `.env`. In `prod`, this behavior will depend on your adapter.
+
+> [!NOTE] To get correct types, environment variables referenced in your code should be declared (for example in an `.env` file), even if they don't have a value until the app is deployed:
+>
+> ```env
+> MY_FEATURE_FLAG=
+> ```
+>
+> You can override `.env` values from the command line like so:
+>
+> ```sh
+> MY_FEATURE_FLAG="enabled" npm run dev
+> ```
+
+For example, suppose the buildtime environment variables were set like this:
+
+```env
+ENVIRONMENT=production
+PUBLIC_BASE_URL=http://site.com
+PUBLIC_VERSION=1
+```
+
+And then suppose at runtime the environment variables were set like this:
+
+```env
+ENVIRONMENT=production
+PUBLIC_BASE_URL=http://not-the-same-site.com
+PUBLIC_VERSION=9001
+```
+
+Assuming the `publicPrefix` is set to `PUBLIC_` and the `privatePrefix` is not set (the default behaviour), this is what would happen at runtime:
 
 ```ts
 import { env } from '$env/dynamic/public';
-console.log(env.PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE);
+
+console.log(env.ENVIRONMENT); // => undefined, not public
+console.log(env.PUBLIC_BASE_URL); // => "http://not-the-same-site.com"
+console.log(env.PUBLIC_VERSION); // => "9001"
+
+import { ENVIRONMENT, PUBLIC_BASE_URL, PUBLIC_VERSION } from '$env/static/public';
+
+console.log(env.ENVIRONMENT); // => undefined, throws error during build
+console.log(env.PUBLIC_BASE_URL); // => "http://site.com"
+console.log(env.PUBLIC_VERSION); // => "1"
 ```

packages/kit/src/types/synthetic/$env+static+private.md

@@ -1,19 +1,30 @@
-Environment variables [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env`. Like [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private), this module cannot be imported into client-side code. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](https://svelte.dev/docs/kit/configuration#env) (if configured).
+This module provides access to environment variables that are injected _statically_ into your bundle at buildtime and are limited to _private_ access.
 
-_Unlike_ [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private), the values exported from this module are statically injected into your bundle at build time, enabling optimisations like dead code elimination.
+|         | Runtime                                                                    | Buildtime                                                              |
+| ------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Private | [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private) | `$env/static/private`                                                  |
+| Public  | [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public)   | [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public) |
 
-```ts
-import { API_KEY } from '$env/static/private';
-```
+Environment variables are [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env` at build time and then statically injected into your bundle at build time, enabling optimisations like dead code elimination.
 
-Note that all environment variables referenced in your code should be declared (for example in an `.env` file), even if they don't have a value until the app is deployed:
+**_Private_ access:**
 
+- This module (and [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private)) cannot be imported into client-side code.
+- Variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`) are **excluded**.
+- Variables that begin with [`config.kit.env.privatePrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to allow-all) are **included**.
+
+For example, suppose the environment variables were set like this during build:
+
+```env
+ENVIRONMENT=production
+PUBLIC_BASE_URL=http://site.com
 ```
-MY_FEATURE_FLAG=""
-```
 
-You can override `.env` values from the command line like so:
+Assuming the `publicPrefix` is set to `PUBLIC_` and the `privatePrefix` is not set (the default behaviour), this is what would happen at runtime, even if the environment variables at runtime are different:
+
+```ts
+import { ENVIRONMENT, PUBLIC_BASE_URL } from '$env/static/private';
 
-```sh
-MY_FEATURE_FLAG="enabled" npm run dev
+console.log(ENVIRONMENT); // => "production"
+console.log(PUBLIC_BASE_URL); // => undefined, throws error during build
 ```

packages/kit/src/types/synthetic/$env+static+public.md

@@ -1,7 +1,29 @@
-Similar to [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code.
+This module provides access to environment variables that are injected _statically_ into your bundle at buildtime and are _publicly_ accessible.
 
-Values are replaced statically at build time.
+|         | Runtime                                                                    | Buildtime                                                                |
+| ------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Private | [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private) | [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private) |
+| Public  | [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public)   | `$env/static/public`                                                     |
+
+Environment variables are [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env` at build time and then statically injected into your bundle at build time, enabling optimisations like dead code elimination.
+
+**_Public_ access:**
+
+- This module (and [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public)) _can_ be imported into client-side code.
+- **Only** variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`) are included.
+
+For example, suppose the environment variables were set like this during build:
+
+```env
+ENVIRONMENT=production
+PUBLIC_BASE_URL=http://site.com
+```
+
+Assuming the `publicPrefix` is set to `PUBLIC_` and the `privatePrefix` is not set (the default behaviour), this is what would happen at runtime, even if the environment variables at runtime are different:
 
 ```ts
-import { PUBLIC_BASE_URL } from '$env/static/public';
+import { ENVIRONMENT, PUBLIC_BASE_URL } from '$env/static/public';
+
+console.log(ENVIRONMENT); // => undefined, throws error during build
+console.log(PUBLIC_BASE_URL); // => "http://site.com"
 ```