Document resolution and runtime context

[rsgalloway]

This pull request introduces significant improvements to documentation, clarifies the runtime context and variable expansion mechanisms, and updates the environment variable for the default stack name. It also adds comprehensive tests to verify import-time settings. The most important changes are:

Documentation and User Guidance Improvements:

• Added new documentation on variable expansion, YAML transformation tags, evaluation order, runtime controls, and name-collision behavior, with composed examples and cross-references between topics (docs/expansion.md, docs/runtime-context.md, docs/api.md, docs/index.md, docs/secrets.md). [1] [2] [3] [4] [5] [6] [7]

• Clarified the timing and precedence of runtime context variables, and explained the difference between stack data and runtime controls, including how collisions are handled. [1] [2] [3]

• Improved documentation for supported variable modifiers, YAML tags, and the evaluation order of expansion and resolution, highlighting unsupported Bash forms and the behavior of assignment operators. [1] [2] [3] [4]

Configuration and Environment Variable Updates:

• Changed the environment variable for the default stack name from DEFAULT_ENV_STACK to DEFAULT_NAMESPACE throughout the codebase and documentation, and clarified its usage and precedence. [1] [2] [3]

Testing Enhancements:

• Added tests to verify that the DEFAULT_NAMESPACE setting is correctly read at import time and that explicit stack selection works as intended in both CLI and Python API usage.

These changes improve clarity for users, ensure correct and predictable runtime behavior, and enhance test coverage for configuration handling.

[Copilot]

🟡 Changes recommended

A critical test invocation bug prevents the intended API paths from being exercised.

1 open issue

• Pass the optional stack name as a single argument · New

What changed in this PR

This PR documents runtime context and variable expansion, renames the default namespace environment variable, and adds import-time configuration tests.

Changes:

• Added documentation for expansion, YAML tags, evaluation order, and runtime controls.
• Replaced DEFAULT_ENV_STACK with DEFAULT_NAMESPACE.
• Added subprocess tests for CLI and Python API behavior.

File	Description
tests/​test_config.py	Tests import-time namespace behavior.
lib/​envstack/​config.py	Reads DEFAULT_NAMESPACE.
docs/​secrets.md	Clarifies encoding and tag references.
docs/​runtime-context.md	Documents runtime controls and collisions.
docs/​index.md	Adds documentation navigation links.
docs/​expansion.md	Documents expansion and YAML transformations.
docs/​api.md	Links to runtime configuration guidance.
CHANGELOG.md	Records configuration and documentation changes.

_{Review effort: Lite}