fix(config): fix 8 DX bugs found field-testing the --config/--profile precedence changes

A field-test pass against this branch's config-loading changes (multi-file --config
merging, profile precedence, config get/set) found 8 real, live-reproduced issues and
fixes them all, each with a failing test committed first:

- config set/delete/format silently edited only the FIRST --config file while config
  get reported the fully-merged value -- a false-success bug whenever a later file also
  set the same key. Now refuses ambiguous multi-file --config with a clear error
  (pkg/config/config_edit.go: new ErrAmbiguousConfigFile/ResolveConfigOverride, shared
  by cmd/config/operations.go and the duplicate in pkg/mcp/config/config.go).
- ATMOS_CONFIG/ATMOS_CONFIG_PATH with multiple comma-separated values worked for some
  commands (via pkg/config's own os.Args/env fallback) but broke ~40 others reading
  these flags through pkg/flags' Viper-based ParseGlobalFlags, which splits env-sourced
  values on whitespace, not commas. Fixed once at that shared choke point by exporting
  the existing --profile fix (parseViperProfilesFromEnv -> cfg.FixViperEnvStringSliceQuirk)
  and applying it there too.
- profiles.base_path declared in a non-first --config file resolved against the FIRST
  file's directory regardless of which file actually declared it, silently failing to
  find profiles that exist. Added per-file directory tracking (mirroring the existing
  base_path tracking in mergeFiles) threaded through to discoverProfileLocations.
- Vendor/workflow error messages (ErrEmptySources, ErrMissingVendorConfigDefinition,
  ErrDuplicateComponents, ErrComponentNotDefined, ErrNoComponentsWithTags, and others)
  still leaked absolute paths right next to the "Vendoring from" line already fixed in
  the prior commit -- a half-fixed pattern. Wrapped 13 sites in displayPath(), plus
  fixed a copy/paste bug in one workflow directory-read error that showed the raw
  unresolved config value instead of the path actually searched.
- displayPath() itself was silently defeated whenever the working directory was reached
  through a symlink (e.g. macOS's /tmp), because os.Getwd() preserves the logical $PWD
  path while git-root-discovery-resolved config paths are physical. Fixed with a
  two-attempt comparison (raw first, then both sides resolved via the directory, since
  the target file often doesn't exist yet).
- --config-path always wins over --config regardless of CLI argument order (undocumented,
  now documented, not code-changed -- effort didn't justify a fix for this ordering nuance).
- Documented the previously-undocumented ATMOS_CONFIG/ATMOS_CONFIG_PATH env vars and
  fixed --config's flag-type description on config-set/delete/format.mdx (all three
  incorrectly said "string" instead of "string slice").

Also updates the field-test skill to default to testing the current branch's diff
against its base branch when no explicit target is given, instead of asking.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: osterman

.claude/skills/field-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: field-test
-description: "Hands-on manual DX test pass of a feature or CLI command: read the real implementation and tests, hypothesize plausible user misunderstandings and misuse automated tests don't cover, build durable fixtures, execute for real against real state, and report ranked findings. Investigation only — never fixes anything found. Invoke on explicit requests like 'field test X' / 'do a DX test pass on X' / 'find vibe-coded slop in X'."
-argument-hint: "Feature or command to test, e.g. 'atmos vendor pull'"
+description: "Hands-on manual DX test pass of a feature or CLI command: read the real implementation and tests, hypothesize plausible user misunderstandings and misuse automated tests don't cover, build durable fixtures, execute for real against real state, and report ranked findings. Investigation only — never fixes anything found. Defaults to testing whatever the current branch changed vs its base branch when no explicit target is given. Invoke on explicit requests like 'field test X' / 'do a DX test pass on X' / 'find vibe-coded slop in X' / 'field test this branch'."
+argument-hint: "Feature or command to test, e.g. 'atmos vendor pull' (omit to default to this branch's change)"
 metadata:
   copyright: Copyright Cloud Posse, LLC 2026
   version: "1.0.0"
@@ -10,8 +10,17 @@ metadata:
 # Field Test
 
 Hands-on, adversarial test pass of **`$ARGUMENTS`** (the feature/command named when this skill
-was invoked, e.g. `atmos vendor pull`). If no target was given, ask which feature/command to test
-before starting.
+was invoked, e.g. `atmos vendor pull`).
+
+**If no target was given, default to the change introduced on the current branch** rather than
+asking. Determine the base branch (the upstream tracking branch via
+`git rev-parse --abbrev-ref --symbolic-full-name @{u}`, falling back to `origin/main`/`main` if
+no upstream is configured), then run `git diff <base>...HEAD --stat` (and the full diff for
+context) to see what actually changed. Derive the test target from that diff — the CLI
+command(s), flag(s), config option(s), or subsystem the changed files implement — and state
+explicitly what you inferred and why before proceeding to Phase 1. Only fall back to asking the
+user if the diff is empty (nothing to test) or spans multiple unrelated features with no coherent
+single target (ask which one to focus on, don't silently pick one).
 
 Goal: catch "vibe-coded slop" — behavior that looks fine in code review but breaks or misleads a
 real user — not to re-run what automated tests already cover. Anticipate plausible user
@@ -27,10 +36,18 @@ The goal is a map of "documented or plausible usage" minus "already tested" = wh
 verification. This phase is broad, read-only research — delegate it to `Agent subagent_type:
 "Explore"` (1-3 agents in parallel, one per bullet below) rather than doing it all serially inline.
 
+When defaulting to the current branch (no explicit target given), scope every bullet below to the
+target inferred from the branch diff — don't research the whole surrounding subsystem when the
+branch only touched one corner of it. If the branch's changed files span more than one command or
+package, treat each as a separate target to cover in Phase 2-4, prioritized by how much of the
+diff each accounts for.
+
 - **Implementation** — the actual code, not just its docs or the skill describing it. Per this
   repo's conventions, business logic lives in narrow `pkg/` packages, not `internal/exec/` (being
   phased out) — check both `cmd/<command>/` (thin call site) and the `pkg/` package(s) it
-  delegates to for the real logic and error paths.
+  delegates to for the real logic and error paths. When defaulting from a branch diff, read the
+  diff itself first (not just the post-change files) — the diff shows what changed *from*,
+  which is exactly where a regression or half-finished edge case would show up.
 - **Docs and skills** — every relevant page under `website/docs/cli/commands/`, the matching
   `.claude/skills/atmos-*` skill(s) for the subsystem, and any README describing the feature. Note
   anything phrased with confidence you haven't independently confirmed against the code — docs and

cmd/config/operations.go

@@ -158,12 +158,16 @@ func init() {
 }
 
 // resolveConfigFile picks the atmos.yaml to edit. The inherited persistent
-// --config flag (first entry) acts as an explicit override; otherwise the file
-// is discovered in the current directory or git root.
+// --config flag acts as an explicit override when it names exactly one file;
+// otherwise the file is discovered in the current directory or git root.
 func resolveConfigFile(cmd *cobra.Command) (string, error) {
-	override := ""
-	if cfgFiles, _ := cmd.Flags().GetStringSlice("config"); len(cfgFiles) > 0 {
-		override = cfgFiles[0]
+	cfgFiles, _ := cmd.Flags().GetStringSlice("config")
+	override, err := cfg.ResolveConfigOverride(cfgFiles)
+	if err != nil {
+		return "", errUtils.Build(errUtils.ErrInvalidArgumentError).
+			WithExplanation(err.Error()).
+			WithHint("Pass a single --config file to config set/delete/format, or edit the target file directly.").
+			Err()
 	}
 
 	file, err := cfg.ResolveEditableConfigFile(atmosConfigPtr, override)

cmd/config/operations_test.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 	"testing"
 
+	ckerrors "github.com/cockroachdb/errors"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 	"github.com/stretchr/testify/assert"
@@ -136,6 +137,29 @@ func TestResolveConfigFile_Error(t *testing.T) {
 	require.ErrorIs(t, err, errUtils.ErrInvalidArgumentError)
 }
 
+// TestResolveConfigFile_MultipleConfigFilesAmbiguous guards against a bug found during a
+// field-test pass on cloudposse/atmos#2867/#2868: resolveConfigFile silently used only the
+// FIRST --config file (cfgFiles[0]) when multiple were given, so `config set --config a,b
+// logs.level X` reported success editing a.yaml while the actual effective value (what `config
+// get` reports, and what every other atmos command uses) stayed unchanged whenever b.yaml also
+// set that key -- a false success, not just a stale-value bug.
+func TestResolveConfigFile_MultipleConfigFilesAmbiguous(t *testing.T) {
+	dir := t.TempDir()
+	fileA := filepath.Join(dir, "a.yaml")
+	fileB := filepath.Join(dir, "b.yaml")
+	require.NoError(t, os.WriteFile(fileA, []byte("settings:\n  enabled: true\n"), 0o644))
+	require.NoError(t, os.WriteFile(fileB, []byte("settings:\n  enabled: false\n"), 0o644))
+
+	cmd := &cobra.Command{}
+	cmd.Flags().StringSlice("config", []string{fileA, fileB}, "")
+
+	_, err := resolveConfigFile(cmd)
+	require.ErrorIs(t, err, errUtils.ErrInvalidArgumentError)
+	details := strings.Join(ckerrors.GetAllDetails(err), "\n")
+	assert.Contains(t, details, "a.yaml")
+	assert.Contains(t, details, "b.yaml")
+}
+
 func TestConfigGetCommand_MissingValue(t *testing.T) {
 	dir := t.TempDir()
 	file := filepath.Join(dir, "atmos.yaml")

internal/exec/describe_workflows_test.go

@@ -125,7 +125,7 @@ workflows:
 				},
 			},
 			wantErr:     true,
-			errContains: "the workflow directory 'nonexistent' does not exist",
+			errContains: "workflow directory does not exist: 'nonexistent'",
 		},
 	}
 
@@ -362,3 +362,29 @@ func TestExecuteDescribeWorkflows_EmptyWorkflowsDirectory(t *testing.T) {
 	assert.Len(t, mapResult, 0)
 	assert.Len(t, allResult, 0)
 }
+
+// TestExecuteDescribeWorkflows_PathLeak guards against a bug found during a field-test pass on
+// cloudposse/atmos#2867/#2868: "the workflow directory '%s' does not exist" interpolated the
+// resolved absolute workflowsDir directly, and the sibling "error reading the directory" message
+// interpolated the raw, unresolved atmosConfig.Workflows.BasePath instead of workflowsDir (the
+// directory actually searched) -- a copy/paste inconsistency with the sibling branch one line up.
+// The pre-existing "nonexistent workflows directory" test above doesn't catch either bug: it
+// leaves BasePath/WorkflowsDirAbsolutePath unset, so getWorkflowsDirToUse falls back to a bare
+// relative path that was never absolute to begin with.
+func TestExecuteDescribeWorkflows_PathLeak(t *testing.T) {
+	resolvedDir := resolvedTempDir(t)
+
+	config := schema.AtmosConfiguration{
+		BasePath: resolvedDir,
+		Workflows: schema.Workflows{
+			BasePath: "nonexistent-workflows-dir",
+		},
+	}
+	require.NoError(t, cfg.AtmosConfigAbsolutePaths(&config))
+
+	_, _, _, err := ExecuteDescribeWorkflows(config)
+
+	require.Error(t, err)
+	assert.NotContains(t, err.Error(), resolvedDir, "error must not leak the machine-specific absolute directory")
+	assert.Contains(t, err.Error(), "nonexistent-workflows-dir")
+}

internal/exec/validate_schema.go

@@ -344,11 +344,37 @@ func displayPath(file string) string {
 	if err != nil {
 		return file
 	}
+	if rel, ok := relPath(cwd, file); ok {
+		return rel
+	}
+	// os.Getwd() preserves the logical $PWD-style path (e.g. macOS's /tmp), while
+	// config-derived absolute paths resolved through git-root discovery resolve symlinks
+	// internally (via go-git/go-billy's filepath.EvalSymlinks) -- so cwd and file can end up in
+	// different (logical vs. physical) forms of the same directory when a symlink is involved.
+	// Retry with both resolved to their canonical physical form; EvalSymlinks on an
+	// already-physical path is a no-op, so this only changes behavior for the mismatched case.
+	// Resolve the DIRECTORY, not file itself: file frequently doesn't exist yet (that's often
+	// exactly why displayPath is being called, e.g. "file not found" errors), and EvalSymlinks
+	// requires its target to exist.
+	resolvedCwd, cwdErr := filepath.EvalSymlinks(cwd)
+	resolvedFileDir, fileErr := filepath.EvalSymlinks(filepath.Dir(file))
+	if cwdErr != nil || fileErr != nil {
+		return file
+	}
+	if rel, ok := relPath(resolvedCwd, filepath.Join(resolvedFileDir, filepath.Base(file))); ok {
+		return rel
+	}
+	return file
+}
+
+// relPath returns file relative to cwd when that relative path stays within cwd (no ".."
+// prefix), and whether it succeeded.
+func relPath(cwd, file string) (string, bool) {
 	rel, err := filepath.Rel(cwd, file)
 	if err != nil || strings.HasPrefix(rel, "..") {
-		return file
+		return "", false
 	}
-	return rel
+	return rel, true
 }
 
 func (av *atmosValidatorExecutor) printValidation(schema string, files []string) (uint, error) {

internal/exec/validate_schema_test.go

@@ -280,6 +280,73 @@ func TestDisplayPath(t *testing.T) {
 	}
 }
 
+// TestDisplayPath_SymlinkedCWD guards against a bug found during a field-test pass on
+// cloudposse/atmos#2867/#2868: when the working directory is reached through a symlink (e.g.
+// macOS's /tmp -> /private/tmp) AND the shell's $PWD reflects the symlinked (logical) path,
+// os.Getwd() returns that logical path (Go's documented $PWD shortcut) while config-derived
+// absolute paths (BasePathAbsolute/VendorDirAbsolutePath/WorkflowsDirAbsolutePath, resolved via
+// git-root discovery which internally calls filepath.EvalSymlinks) return the physical,
+// resolved path -- so filepath.Rel between the two silently fails, and displayPath falls back
+// to the full absolute path, defeating the fix in exactly the environments it was meant to help.
+//
+// Plain os.Chdir alone doesn't reproduce this (it doesn't touch $PWD), so $PWD is set explicitly
+// here to model what a real shell `cd` into a symlinked directory does.
+func TestDisplayPath_SymlinkedCWD(t *testing.T) {
+	tmpDir := t.TempDir()
+	realDir := filepath.Join(tmpDir, "realdir")
+	require.NoError(t, os.MkdirAll(realDir, 0o755))
+
+	symlinkPath := filepath.Join(tmpDir, "symlink")
+	if err := os.Symlink(realDir, symlinkPath); err != nil {
+		t.Skipf("Skipping symlink test: %v", err)
+	}
+
+	resolvedRealDir, err := filepath.EvalSymlinks(realDir)
+	require.NoError(t, err)
+
+	wd, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, os.Chdir(wd)) })
+	require.NoError(t, os.Chdir(symlinkPath))
+	t.Setenv("PWD", symlinkPath)
+
+	// file is built from the RESOLVED (physical) directory, as config-derived absolute paths
+	// are (via git-root discovery's filepath.EvalSymlinks), while os.Getwd() inside displayPath
+	// will see the symlinked (logical) form because $PWD matches it.
+	file := filepath.Join(resolvedRealDir, "vendor.yaml")
+	assert.Equal(t, "vendor.yaml", displayPath(file))
+}
+
+// TestDisplayPath_SymlinkedCWD_BothLogical guards against a regression the first version of the
+// EvalSymlinks fix above introduced: when NO git-root discovery runs (e.g. base_path already
+// absolute, or no .git found), config-derived absolute paths are computed via plain
+// filepath.Abs, which -- like os.Getwd() -- respects the $PWD logical shortcut. So under a
+// symlinked cwd (e.g. macOS's /tmp) with no git repo involved, BOTH cwd and file stay
+// consistently in LOGICAL form and were already directly comparable before any EvalSymlinks
+// normalization. A fix that unconditionally resolves only cwd (not file) breaks this
+// previously-working case by making cwd physical while file stays logical.
+func TestDisplayPath_SymlinkedCWD_BothLogical(t *testing.T) {
+	tmpDir := t.TempDir()
+	realDir := filepath.Join(tmpDir, "realdir")
+	require.NoError(t, os.MkdirAll(realDir, 0o755))
+
+	symlinkPath := filepath.Join(tmpDir, "symlink")
+	if err := os.Symlink(realDir, symlinkPath); err != nil {
+		t.Skipf("Skipping symlink test: %v", err)
+	}
+
+	wd, err := os.Getwd()
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, os.Chdir(wd)) })
+	require.NoError(t, os.Chdir(symlinkPath))
+	t.Setenv("PWD", symlinkPath)
+
+	// file is built from the SAME logical (unresolved) symlink path as cwd, simulating
+	// filepath.Abs's $PWD-shortcut behavior in the no-git-root-discovery case.
+	file := filepath.Join(symlinkPath, "vendor.yaml")
+	assert.Equal(t, "vendor.yaml", displayPath(file))
+}
+
 func TestBuiltinConfigSchemaMatchesIncludesExistingOptionalDirectories(t *testing.T) {
 	project := t.TempDir()
 	require.NoError(t, os.MkdirAll(filepath.Join(project, "atmos.d"), 0o700))

internal/exec/vendor_utils.go

@@ -174,7 +174,7 @@ func getConfigFiles(path string) ([]string, error) {
 			return nil, ErrVendoringNotConfigured
 		}
 		if os.IsPermission(err) {
-			return nil, fmt.Errorf("%w '%s'. Please check the file permissions", ErrPermissionDenied, path)
+			return nil, fmt.Errorf("%w '%s'. Please check the file permissions", ErrPermissionDenied, displayPath(path))
 		}
 		return nil, fmt.Errorf("An error occurred while accessing the vendoring configuration: %w", err)
 	}
@@ -186,7 +186,7 @@ func getConfigFiles(path string) ([]string, error) {
 		}
 
 		if len(matches) == 0 {
-			return nil, fmt.Errorf("%w '%s'", ErrNoYAMLConfigFiles, path)
+			return nil, fmt.Errorf("%w '%s'", ErrNoYAMLConfigFiles, displayPath(path))
 		}
 		for i, match := range matches {
 			matches[i] = filepath.Join(path, match)
@@ -218,7 +218,7 @@ func mergeVendorConfigFiles(configFiles []string) (schema.AtmosVendorConfig, err
 			source := currentConfig.Spec.Sources[i]
 			if source.Component != "" {
 				if sourceMap[source.Component] {
-					return vendorConfig, fmt.Errorf("%w '%s' found in config file '%s'", ErrDuplicateComponentsFound, source.Component, configFile)
+					return vendorConfig, fmt.Errorf("%w '%s' found in config file '%s'", ErrDuplicateComponentsFound, source.Component, displayPath(configFile))
 				}
 				sourceMap[source.Component] = true
 			}
@@ -247,7 +247,7 @@ func ExecuteAtmosVendorInternal(params *executeVendorOptions) error {
 	// itself stays untouched (and possibly absolute) for the actual file/source resolution below.
 	logInitialMessage(displayPath(params.vendorConfigFileName), params.tags)
 	if len(params.atmosVendorSpec.Sources) == 0 && len(params.atmosVendorSpec.Imports) == 0 {
-		return fmt.Errorf("%w '%s'", ErrMissingVendorConfigDefinition, params.vendorConfigFileName)
+		return fmt.Errorf("%w '%s'", ErrMissingVendorConfigDefinition, displayPath(params.vendorConfigFileName))
 	}
 	// Process imports and return all sources from all the imports and from `vendor.yaml`.
 	sources, _, err := processVendorImports(
@@ -262,7 +262,7 @@ func ExecuteAtmosVendorInternal(params *executeVendorOptions) error {
 	}
 
 	if len(sources) == 0 {
-		return fmt.Errorf("%w %s", ErrEmptySources, params.vendorConfigFileName)
+		return fmt.Errorf("%w %s", ErrEmptySources, displayPath(params.vendorConfigFileName))
 	}
 
 	if err := validateTagsAndComponents(sources, params.vendorConfigFileName, params.component, params.tags); err != nil {
@@ -306,7 +306,7 @@ func validateTagsAndComponents(
 
 		if len(lo.Intersect(tags, componentTags)) == 0 {
 			return fmt.Errorf("%w '%s' tagged with the tags %v",
-				ErrNoComponentsWithTags, vendorConfigFileName, tags)
+				ErrNoComponentsWithTags, displayPath(vendorConfigFileName), tags)
 		}
 	}
 
@@ -316,12 +316,12 @@ func validateTagsAndComponents(
 
 	if duplicates := lo.FindDuplicates(components); len(duplicates) > 0 {
 		return fmt.Errorf("%w %v in the vendor config file '%s' and the imports",
-			ErrDuplicateComponents, duplicates, vendorConfigFileName)
+			ErrDuplicateComponents, duplicates, displayPath(vendorConfigFileName))
 	}
 
 	if component != "" && !slices.Contains(components, component) {
 		return fmt.Errorf("%w component '%s', file '%s'",
-			ErrComponentNotDefined, component, vendorConfigFileName)
+			ErrComponentNotDefined, component, displayPath(vendorConfigFileName))
 	}
 
 	return nil
@@ -592,8 +592,8 @@ func processVendorImports(
 			return nil, nil, fmt.Errorf(
 				"%w '%s' in the vendor config file '%s'. It was already imported in the import chain",
 				ErrDuplicateImport,
-				imp,
-				vendorConfigFile,
+				displayPath(imp),
+				displayPath(vendorConfigFile),
 			)
 		}
 
@@ -605,11 +605,11 @@ func processVendorImports(
 		}
 
 		if slices.Contains(vendorConfig.Spec.Imports, imp) {
-			return nil, nil, fmt.Errorf("%w file '%s'", ErrVendorConfigSelfImport, imp)
+			return nil, nil, fmt.Errorf("%w file '%s'", ErrVendorConfigSelfImport, displayPath(imp))
 		}
 
 		if len(vendorConfig.Spec.Sources) == 0 && len(vendorConfig.Spec.Imports) == 0 {
-			return nil, nil, fmt.Errorf("%w '%s'", ErrMissingVendorConfigDefinition, imp)
+			return nil, nil, fmt.Errorf("%w '%s'", ErrMissingVendorConfigDefinition, displayPath(imp))
 		}
 
 		mergedSources, allImports, err = processVendorImports(atmosConfig, imp, vendorConfig.Spec.Imports, mergedSources, allImports)
@@ -641,10 +641,10 @@ func validateSourceFields(s *schema.AtmosVendorSource, vendorConfigFileName stri
 		s.File = vendorConfigFileName
 	}
 	if s.Source == "" {
-		return fmt.Errorf("%w `%s`", ErrSourceMissing, s.File)
+		return fmt.Errorf("%w `%s`", ErrSourceMissing, displayPath(s.File))
 	}
 	if len(s.Targets) == 0 {
-		return fmt.Errorf("%w for source '%s' in file '%s'", ErrTargetsMissing, s.Source, s.File)
+		return fmt.Errorf("%w for source '%s' in file '%s'", ErrTargetsMissing, s.Source, displayPath(s.File))
 	}
 	if err := version.ValidateVersionRangeConstraints(s.Version, s.Constraints); err != nil {
 		return err