feat: Reorganize environment variables documentation for clarity

[jancurn]

Summary

Clarify the environment variables page by separating run-time from build-time and system from custom.

• Split intro into two sources: System and Custom environment variables
• Call out that system variables are run-time only and never passed to builds, even with Apply environment variables also to the build process enabled
• Group setup methods under Custom environment variables with shorter subsection titles: Define in actor.json and Define in Apify Console
• Extract Secret option and visibility caution into a dedicated Secure environment variables subsection
• Expand Build-time environment variables to explain the Console opt-in and that only custom variables are forwarded

https://claude.ai/code/session_0121d3Sgy1UxMnpVZzBEQCNA

[apify-service-account]

✅ Preview for this PR (commit 1326bd49) is ready at https://pr-2515.preview.docs.apify.com (see action run).

[Copilot]

Pull request overview

This PR reorganizes the Actor environment variables documentation to clearly separate system vs. custom variables and run-time vs. build-time behavior, including security guidance for secrets.

Changes:

• Reworked the introduction to distinguish system and custom environment variables and clarify run/build scope.
• Restructured custom variable setup into actor.json, Console, and a dedicated “Secure environment variables” subsection.
• Expanded build-time coverage to explain the Console opt-in and that only custom variables are forwarded.

Comments suppressed due to low confidence (3)

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

• Docs standards in AGENTS.md say bold should be reserved for UI elements only. Here run and build are conceptual terms (not UI labels), so they should not be bolded; use plain text (and keep bold only for actual UI items like button/menu names).

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).

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

• The JSON example is not valid JSON because it has a trailing comma after the last property ("MYSQL_USER": "my_username",). Since the code fence is marked as json, please make the snippet valid JSON (remove the trailing comma or add another property).

```json
{
  "actorSpecification": 1,
  "name": "dataset-to-mysql",
  "version": "0.1",
  "buildTag": "latest",
  "environmentVariables": {
    "MYSQL_USER": "my_username",
  }
}

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

• Docs standards in AGENTS.md say bold should be reserved for UI elements only. In this paragraph, runs and build are concepts, so remove the bold emphasis (while keeping bold for UI labels like Apply environment variables also to the build process).

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:

[TC-MO]

Blocking: the customer > custom typo at L98.

The other suggestions on new/changed prose (L9, L29, L88) would be good to address while you're in here.

I've also flagged a handful of cleanup opportunities on pre-existing lines.
Feel free to fold them in, or leave them for a follow-up.

[TC-MO]

I would actually remove this whole intro, we've been already doing it in other parts of docs. It brings little to no additional value, and just repeats description.

[TC-MO]

We can remove this sentence, clean up opportunity

[TC-MO]

Remove sentence - clean up opportunity.

[TC-MO]

This admonition serves the same info as the ending of the doc at L261. I would propose to drop this completely fixing duplication issue & the typo at the same time. The ending seems like a more natural fit for this statement either way.