docs: document subprocess environment filtering and the passthrough setting

[JeffreyDallas]

Description

Documents how Solo filters the environment it passes to the external commands it runs (helm, kubectl, kind, container engines), which was previously undocumented anywhere.

Companion to hiero-ledger/solo#5897, which fixes #5895 — EKS IRSA broke because AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE were not on Solo's allowlist. Part of why that needed a bug report is that nothing told users the filtering existed at all; the reporter had to replace the helm binary with a recorder to find it.

New page, Subprocess Environment Filtering:

• why Solo filters rather than forwarding the parent environment
• how to tell from solo.log that a variable was withheld, with the real two-line log shape and both Bash and PowerShell search commands
• the two bounds on that diagnostic — an identifier-shape restriction and a 2000-name ceiling — and that they affect what is reported, never what is forwarded
• how to forward a variable with subprocess.additionalEnvironmentVariables, including the per-command syntax and where the file lives
• why that setting is config-file only and cannot be set via SOLO_*
• the names refused unconditionally — loader hooks, TLS trust overrides, credential/endpoint redirection — and that AWS_ENDPOINT_URL, LD_ and DYLD_ are refused by prefix, so AWS_ENDPOINT_URL_STS cannot redirect the EKS credential exchange
• what the permission checks actually guarantee, separated from what they do not
• current managed-Kubernetes state: EKS IRSA works out of the box; GKE and AKS are unverified and opt-in, with a worked example and a request to report a confirmed set

Also adds a short cross-reference from the existing Using Environment Variables page, which documents variables that configure Solo itself — a distinction not previously drawn, and the likely first place a confused user looks.

Notes for reviewers

Several statements in this page were corrected during review of the companion PR, and the current text is deliberately narrower than the first draft:

• The file is solo-config.yaml, not solo.yaml. ~/.solo/solo.yaml is a leftover from older Solo versions and is deleted automatically by hiero-consensus-node's CITR tooling, so settings placed there would be silently lost. The page warns about the similarly named file.
• The security guarantee is scoped rather than absolute. An earlier draft said every ancestor symlink or non-user-owned directory is rejected and that the file "cannot be swapped". Neither matched the implementation: POSIX must accept root-owned and sticky ancestors, Windows stops before the volume root, and the no-follow descriptor protects only the final component — Node offers no openat, so a directory swap by someone who already has write access on the path is not defended against. The page now separates the guaranteed part from the best-effort part and says so in one sentence.
• The descriptor guarantee is marked POSIX-only, since Windows has no equivalent no-follow open and its symlink check is a check-then-open.
• Windows is documented as not yet usable. The ACL checks exist but have never been run on Windows, and the guarantee there is weaker. Better to say so than to present it as supported.
• The log snippet is copied from a real run. An earlier version put variable names on the summary line; Solo actually writes a summary ending in for that command: followed by withheld from '<command>': lines, so a reader comparing the example to their own log would not have found a match.
• PowerShell equivalents are provided for the log search, the SOLO_HOME override and the permission commands — icacls, not a chmod that does not exist there — and secure the .solo directory as well as the file, since directory write access alone permits replacing it.

Related Issues

• Related to AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE are stripped from helm solo#5895
• Companion to fix: pass EKS workload-identity variables to helm and kubectl solo#5897

Testing

remark-cli --frail passes on both changed files. Rendering was not verified in a local Hugo build.

The GKE/AKS section deliberately says those platforms are not covered rather than listing guessed variable names, matching the code: the companion PR speculatively added AZURE_AUTHORITY_HOST and review correctly identified it as an authority-redirect vector. If someone verifies the required set on a real cluster, the docs and the built-in allowlist should be updated together.