yoi/work-items/closed/20260531-082646-document-env-var-policy/item.md

id: 20260531-082646-document-env-var-policy slug: document-env-var-policy title: Docs: document environment variable policy status: closed kind: task priority: P2 labels: [docs, config, security] created_at: 2026-05-31T08:26:46Z updated_at: 2026-05-31T08:29:40Z assignee: null legacy_ticket: null

Background

Environment variables are currently used for a few practical boundaries: XDG-style path discovery, runtime/socket directories, development overrides, and legacy/provider secret inputs. The user's preference is that this project should avoid environment variables where possible and make any remaining environment-variable surface explicit.

A short investigation found that path resolution is mostly centralized in manifest::paths, while auth/web secret envs and test-only env mutation are more scattered. Normal runtime intentionally does not implicitly load .env files.

Requirements

• Add current documentation for environment-variable policy and supported variables.
• State the design preference clearly: avoid new environment variables when manifest/profile/config/typed secret references are better.
• Document the currently supported categories:
  • core path/resource discovery;
  • runtime/socket/registry discovery;
  • Pod runtime command development override;
  • provider/WebSearch credential references;
  • external compatibility variables such as Codex home;
  • test/build/example-only environment variables.
• Clarify that normal runtime must not implicitly load .env files.
• Identify cleanup direction without implementing unrelated refactors in this ticket.

Acceptance criteria

• A user/developer-facing docs page explains environment-variable policy and current variables.
• Existing Nix/config docs link to the new policy page where relevant.
• Documentation does not expose secret values or read ignored secret-like files.
• ./tickets.sh doctor and git diff --check pass.