docs+config: surface the two env-variable expansion syntaxes (#2615)

[dgageot]

Stop-gap for #2615 — surfaces the silently-failing variable-expansion mismatch in agent YAML without changing runtime behavior.

Background

Agent YAML uses two incompatible expansion syntaxes:

• JS template literals — ${env.X} (with || defaults, ternaries, tool calls). Used in description, welcome_message, instruction, commands, headers, and api_config. Backed by pkg/js.
• Shell-style — $VAR, ${VAR}, ~. Used in path-like fields (working_dir, toolset path) and toolset/hook env values. Backed by os.Expand / pkg/path.

Mixing them up (e.g. ${USER} in a description, or ${env.HOME} in a working_dir) is a silent no-op: the literal string is passed through. This bites users every few weeks.

PR #2710 attempts a runtime unification but is blocked on design (reflection-based walker, breaking Source interface). This PR takes the smaller steps the issue explicitly invited:

1. Document the rules.
2. Warn at config-load time so the silent failure becomes visible.

Runtime behavior is unchanged.

What's in this PR

Documentation

docs/configuration/overview/index.md gets a new "Variable Expansion in Config Fields" section with a quick-reference table:

Field	${env.X}	$X / ${X}	~
description, welcome_message	✓	✗	✗
instruction (agent + toolset)	✓	✗	✗
commands.*	✓	✗	✗
headers, remote.headers	✓	✗	✗
api_config.endpoint/headers	✓	✗	✗
working_dir, path	✗	✓	✓
env values (toolset/hook)	✗	✓	✗

Cross-links added from docs/configuration/agents/index.md and docs/configuration/tools/index.md.

Warnings at config-load

pkg/config/expansion_warnings.go adds warnExpansionMismatches, called at the end of config.Load. It walks every agent + toolset + hook and emits a single slog.Warn per offending occurrence with location, field, variable, and a link to #2615.

Two cases:

• Shell-style in JS field: ${IDENT} in description, welcome_message, instruction, commands, headers (headers, remote.headers, api_config.headers), api_config.endpoint, api_config.instruction. Suppressed when the same value also contains a real ${env.X} so legitimate JS templates with non-env interpolations don't false-positive.
• JS-style in shell field: ${env.X} in working_dir, toolset path, toolset env, script shell working_dir/env, all hook working_dir/env.

The warning logs the variable name and location only — never the full field value, since path:/env: values often contain credentials.

Tests

10 table tests in pkg/config/expansion_warnings_test.go cover both directions, false-positive avoidance, secret non-leakage, lowercase identifiers, mixed JS+shell headers, APIConfig, ScriptShellToolConfig, and hooks. All run with t.Parallel() because the logger is dependency-injected (no global slog.Default() mutation).

Validation

• task build ✓
• task test ✓ (all packages pass with -race)
• task lint ✓ (0 issues, custom lint clean, go.mod tidy)

Commits

docs: clarify which env-variable expansion syntax applies per field
feat(config): warn on mismatched env-variable expansion syntax
docs: correct env-value expansion syntax
fix(config): harden expansion mismatch warnings

The two fix:/docs: follow-ups came out of self-review; happy to squash on merge.

Out of scope

• Runtime unification of the two syntaxes (fix: centralize environment variable expansion at config boundary #2710).
• Threading the agent's EnvProvider through pkg/path/expand.go so secrets / env files reach working_dir. Tracked as a follow-up — it's a small, contained change once this lands.

Closes part of #2615 (documentation + visibility); leaves it open for the runtime unification.

[docker-agent]

Assessment: 🟢 APPROVE

The expansion-warning subsystem is well-structured with good test coverage. All medium-severity hypotheses were dismissed: types.Command fields are fully covered (Instruction is set for both simple-string and struct-format commands), and the broad suppression in warnJSField is an intentional documented design tradeoff. One low-severity inconsistency was found between the fast-path guard and the regex in warnPathField.

[docker-agent]

[LOW] warnPathField fast-path guard misses whitespace variants like ${ env.X}

The fast-path early return uses strings.Contains(value, "${env.") which does not match ${ env.X } (whitespace after ${). However, the jsEnvRefStrict regex (\$\{\s*env\.) does allow leading whitespace inside ${}, and JavaScript template literals also permit this (${ env.HOME } is valid JS that the evaluator would expand). A user who writes ${ env.HOME}/work in a working_dir field would get no warning despite the JS evaluator being able to process it.

Suggested fix: widen the fast-path guard to check for "${" instead of the full "${env.", or remove it and rely solely on the regex:

// Before
if value == "" || !strings.Contains(value, "${env.") {

// After
if value == "" || !strings.Contains(value, "${") {

This is a minor gap — spaces in ${env.X} are rare in practice — but the inconsistency between the guard and the regex is a latent correctness issue.