feat: Reorganize environment variables documentation for clarity

sources/platform/actors/development/programming_interface/environment_variables.md

@@ -15,26 +15,28 @@ import TabItem from '@theme/TabItem';
 
 ## How to use environment variables in an Actor
 
-You can set up environment variables for your Actor in two ways:
+Environment variables come from two sources:
 
-- [Set up environment variables in `actor.json`](#set-up-environment-variables-in-actorjson)
-- [Set up environment variables in Apify Console](#set-up-environment-variables-in-apify-console)
-
-:::info Environment variable precedence
+- [System environment variables](#system-environment-variables) - set automatically by the Apify platform for each Actor run.
+- [Custom environment variables](#custom-environment-variables) - defined by the Actor owner, either in `.actor/actor.json` or in Apify Console.
 
-Your local `.actor/actor.json` file overrides variables set in Apify Console. To use Console variables, remove the `environmentVariables` key from the local file.
-
-:::
+By default, both kinds of variables are passed only to the Actor **run**, not to the **build**. For variables passed to the build process (Docker build arguments), see [Build-time environment variables](#build-time-environment-variables).
 
 Check out how you can [access environment variables in Actors](#access-environment-variables).
 
 ## System environment variables
 
 Apify sets several system environment variables for each Actor run. These variables provide essential context and information about the Actor's execution environment.
 
+:::info Run-time only
+
+System environment variables are set only when the Actor runs. They are not available during the build process, even if you enable **Apply environment variables also to the build process** in the Actor's **Code** > **Environment variables** section. That option only forwards user-defined environment variables to the build; system variables such as `ACTOR_RUN_ID`, `APIFY_TOKEN`, or `ACTOR_DEFAULT_DATASET_ID` are never passed to builds.
+
+:::
+
 Here's a table of key system environment variables:
 
-| Environment Variable | Description |
+| Environment variable | Description |
 | -------------------- | ----------- |
 | `ACTOR_ID` | ID of the Actor. |
 | `ACTOR_FULL_NAME` | Full technical name of the Actor, in the format `owner-username/actor-name`. |
@@ -83,7 +85,20 @@ All date-related variables use the UTC timezone and are in [ISO 8601](https://en
 :::
 <!-- vale Microsoft.RangeFormat = YES -->
 
-## Set up environment variables in `actor.json`
+## Custom environment variables
+
+Actor owners can define custom environment variables to pass additional configuration to their Actors. There are two ways to set them up:
+
+- [Set up environment variables in `actor.json`](#set-up-environment-variables-in-actorjson)
+- [Set up environment variables in Apify Console](#set-up-environment-variables-in-apify-console)
+
+:::info Environment variable precedence
+
+Your local `.actor/actor.json` file overrides variables set in Apify Console. To use Console variables, remove the `environmentVariables` key from the local file.
+
+:::
+
+### Set up environment variables in `actor.json`
 
 Actor owners can define custom environment variables in `.actor/actor.json`. All keys from `environmentVariables` will be set as environment variables into the Apify platform after you push Actor to Apify.
 
@@ -105,9 +120,9 @@ Be aware that if you define `environmentVariables` in `.actor/actor.json`, it on
 
 :::
 
-## Set up environment variables in Apify Console
+### Set up environment variables in Apify Console
 
-Actor owners can define custom environment variables to pass additional configuration to their Actors. To set custom variables:
+To set custom variables in Apify Console:
 
 1. Go to your Actor's **Source** page in Apify Console
 
@@ -132,106 +147,116 @@ Once you start a build, you cannot change its environment variables. To use diff
 Learn more in [Builds](../builds_and_runs/builds.md).
 :::
 
-## Access environment variables
+### Use the `Configuration` class
 
-You can access environment variables in your code as follows:
+For more convenient access to Actor configuration, use the [`Configuration`](/sdk/js/reference/class/Configuration) class
 
 <Tabs groupId="main">
 <TabItem value="JavaScript" label="JavaScript">
 
-In Node.js, use the `process.env` object:
-
 ```js
 import { Actor } from 'apify';
 
 await Actor.init();
 
-// get MYSQL_USER
-const mysql_user = process.env.MYSQL_USER
-
-// print MYSQL_USER to console
-console.log(mysql_user);
+// get current token
+const token = Actor.config.get('token');
+// use different token
+Actor.config.set('token', 's0m3n3wt0k3n');
 
 await Actor.exit();
 ```
 
 </TabItem>
 <TabItem value="Python" label="Python">
 
-In Python, use the `os.environ` dictionary:
-
 ```python
-import os
-print(os.environ['MYSQL_USER'])
-
 from apify import Actor
 
 async def main():
     async with Actor:
-        # get MYSQL_USER
-        mysql_user = os.environ['MYSQL_USER']
+        old_token = Actor.configuration.token
+        Actor.log.info(f'old_token = {old_token}')
 
-        # print MYSQL_USER to console
-        print(mysql_user)
+        # use different token
+        Actor.configuration.token = 's0m3n3wt0k3n'
+
+        new_token = Actor.configuration.token
+        Actor.log.info(f'new_token = {new_token}')
 ```
 
 </TabItem>
 </Tabs>
 
-## Use the `Configuration` class
+## Access environment variables
 
-For more convenient access to Actor configuration, use the [`Configuration`](/sdk/js/reference/class/Configuration) class
+You can access environment variables in your code as follows:
 
 <Tabs groupId="main">
 <TabItem value="JavaScript" label="JavaScript">
 
+In Node.js, use the `process.env` object:
+
 ```js
 import { Actor } from 'apify';
 
 await Actor.init();
 
-// get current token
-const token = Actor.config.get('token');
-// use different token
-Actor.config.set('token', 's0m3n3wt0k3n');
+// get MYSQL_USER
+const mysql_user = process.env.MYSQL_USER
+
+// print MYSQL_USER to console
+console.log(mysql_user);
 
 await Actor.exit();
 ```
 
 </TabItem>
 <TabItem value="Python" label="Python">
 
+In Python, use the `os.environ` dictionary:
+
 ```python
+import os
+print(os.environ['MYSQL_USER'])
+
 from apify import Actor
 
 async def main():
     async with Actor:
-        old_token = Actor.configuration.token
-        Actor.log.info(f'old_token = {old_token}')
-
-        # use different token
-        Actor.configuration.token = 's0m3n3wt0k3n'
+        # get MYSQL_USER
+        mysql_user = os.environ['MYSQL_USER']
 
-        new_token = Actor.configuration.token
-        Actor.log.info(f'new_token = {new_token}')
+        # print MYSQL_USER to console
+        print(mysql_user)
 ```
 
 </TabItem>
 </Tabs>
 
 ## Build-time environment variables
 
-You can also use environment variables during the Actor's build process. In this case, they function as Docker build arguments. To use them in your Dockerfile, include `ARG` instruction:
+The environment variables described above apply only to Actor **runs**. To make a variable available during the Actor's **build** process, you need to opt in explicitly. In this case, the variables function as Docker build arguments. To use them in your Dockerfile, include the `ARG` instruction:
 
 ```docker
 ARG MY_BUILD_VARIABLE
 RUN echo $MY_BUILD_VARIABLE
 ```
 
+To pass your user-defined environment variables to the build, enable **Apply environment variables also to the build process** in your Actor's **Code** > **Environment variables** section in Apify Console.
+
+:::caution Only user-defined variables are passed to the build
+
+Even with **Apply environment variables also to the build process** enabled, only the variables you define in the Actor's **Environment variables** section are forwarded to the build. The Apify [system environment variables](#system-environment-variables) (such as `ACTOR_RUN_ID`, `APIFY_TOKEN`, or `ACTOR_DEFAULT_DATASET_ID`) are never available at build time, since the build is not associated with a specific run.
+
+:::
+
 :::caution Variables set during the build
 
 Build-time environment variables are not suitable for secrets, as they are not encrypted.
 
 :::
 
+Once a build starts, its environment variables are frozen into that build's Docker image. To change them, you need to create a new build. Learn more in [Builds](../builds_and_runs/builds.md).
+
 By leveraging environment variables effectively, you can create more flexible and configurable Actors that adapt to different execution contexts and user requirements.