docs: Improve Actors environment variables docs

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

@@ -16,18 +16,18 @@ import TabItem from '@theme/TabItem';
 
 ## How to use environment variables in Actors
 
-There are two ways how you can set up environment variables for Actors:
+You can set up environment variables for Actors in two ways:
 
 - [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 variables overwrite
+:::info Environment variable precedence
 
-After setting up variables in Apify Console, remove the `environmentVariables` from `.actor/actor.json`. Otherwise, variables from `.actor/actor.json` will override variables 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.
 
 :::
 
-See how you can [access environment variables in Actors](#access-environment-variables).
+Check out how you can [access environment variables in Actors](#access-environment-variables).
 
 ## System environment variables
 
@@ -83,9 +83,9 @@ 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
+## 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 Apify platform after you push Actor to Apify.
+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.
 
 ```json
 {
@@ -94,11 +94,17 @@ Actor owners can define custom environment variables in `.actor/actor.json`. All
   "version": "0.1",
   "buildTag": "latest",
   "environmentVariables": {
-    "api_token": "token_123",
+    "MYSQL_USER": "my_username",
   }
 }
 ```
 
+:::info Git-workflow with actor.json
+
+Be aware that if you define `environmentVariables` in `.actor/actor.json`, it only works with [Apify CLI](/cli). If you use a Git workflow for Actor development, the environment variables will not work properly, and we encourage you to define them 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:
@@ -109,12 +115,13 @@ Actor owners can define custom environment variables to pass additional configur
 
 1. Add your custom variables.
 
-For sensitive data like API keys or passwords, enable the **Secret** option. This encrypt the value and redacts it from logs to prevent accidental exposure.
+For sensitive data like API keys or passwords, enable the **Secret** option. This will encrypt the value and redact it from logs to prevent accidental exposure.
 
 :::info Build-time variables
 
-Custom environment variables are set during the Actor's build process and cannot be changed for existing builds. For more information, check out the [Builds](../builds_and_runs/builds.md) page.
+Once you start a build, you cannot change its environment variables. To use different variables, you must create a new build.
 
+Learn more in [Builds](../builds_and_runs/builds.md).
 :::
 
 ## Access environment variables
@@ -131,11 +138,11 @@ import { Actor } from 'apify';
 
 await Actor.init();
 
-// get api_token
-const api_token = process.env.api_token
+// get MYSQL_USER
+const mysql_user = process.env.MYSQL_USER
 
-// print api_token to console
-console.log(api_token);
+// print MYSQL_USER to console
+console.log(mysql_user);
 
 await Actor.exit();
 ```
@@ -147,25 +154,25 @@ In Python, use the `os.environ` dictionary:
 
 ```python
 import os
-print(os.environ['api_token'])
+print(os.environ['MYSQL_USER'])
 
 from apify import Actor
 
 async def main():
     async with Actor:
-        # get api_token
-        userId = os.environ['api_token']
+        # get MYSQL_USER
+        mysql_user = os.environ['MYSQL_USER']
 
-        # print api_token to console
-        print(userId)
+        # print MYSQL_USER to console
+        print(mysql_user)
 ```
 
 </TabItem>
 </Tabs>
 
-## Access system environment variables
+## Use the `Configuration` class
 
-For more convenient access to Actor system variables and other configuration, use the [`Configuration`](/sdk/js/reference/class/Configuration) class 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">
@@ -213,7 +220,7 @@ ARG MY_BUILD_VARIABLE
 RUN echo $MY_BUILD_VARIABLE
 ```
 
-:::caution Insecure build variables
+:::caution Variables set during the build
 
 Build-time environment variables are not suitable for secrets, as they are not encrypted.