[linghengqian]

Part of #737 (item 3, "Change the default of path.mode to baseline").

What changes

path.mode defaults to baseline. The default was legacy, which keeps every PATH entry in front of vfox's first directory in front of it, so a system directory that macOS path_helper or the Windows machine PATH put there kept winning over the version vfox use selected (#337, #732). baseline moves what was already in PATH when vfox activate ran behind vfox's directories, and keeps what is added afterwards (a virtualenv, the $PNPM_HOME of pnpm setup) in front. The way back is one line: vfox config path.mode legacy.

Checked with real binaries, built from main and from this branch. The shell's PATH is <system dir with alphatool>:<vfox sdks dir>:/usr/bin:/bin when vfox activate bash runs, which is the shape behind #337 and #732:

	alphatool runs	PATH starts with
main (default legacy)	the system's	system dir, vfox dir
this branch, nothing configured	vfox's	vfox dir, system dir
this branch + vfox config path.mode legacy	the system's	system dir, vfox dir
this branch + path.preserve listing the system dir	the system's	system dir, vfox dir

Code

• config.DefaultPathMode names the default in one place. EmptyPath, both fallbacks of Path.EffectiveMode and the starting mode of pathPolicy() use it: the four places listed in Follow-ups of #736: plugin updates, the path.mode default and vfox config #737.
• The open question in Follow-ups of #736: plugin updates, the path.mode default and vfox config #737, whether a typo should land on the new default: yes. An empty or unknown value is the default, as it was before, so a typo does not fail vfox env, which runs at every prompt.
• EffectiveMode has to name legacy as a case of its own now. Flipping only the fallbacks would turn mode: legacy into baseline. I removed the case to see: 12 tests in all four packages fail.
• A shell without a recorded baseline still behaves like legacy in every mode, so upgrading does not reorder the PATH of a shell that is already running. It gets the new default when it is restarted. TestEnvWithoutABaselineBehavesLikeLegacyInEveryMode covers the unconfigured case too.
• The path.shadowed hint for a directory that was already in PATH at activation said to run vfox config path.mode baseline. That finding can only come up in legacy mode now (baseline moves such a directory behind vfox's, and without a recorded baseline the source is "unknown"), so the hint says that first. The other two hints are still right and unchanged.

Tests

The eleven tests that the flip breaks, as counted in #737, are updated: 4 in cmd/commands, 4 in internal/config, 2 in internal/env, 1 in internal/sdk.

Five more kept passing for the wrong reason. They used baseline as the value that has to survive a merge, a save, the first run with a shared VFOX_HOME or an alias change; once it is the default, losing it would not show. They use legacy now: TestMergePath, TestPathRoundTripThroughYAML, TestSharedSettingsApplyOverANewUserConfigFile, TestAFreshUserFollowsTheSharedConfig, TestAliasChangesLeaveTheRestOfTheUserConfigAlone.

New: TestDefaultPathModeIsBaseline, and the unconfigured and legacy cases in the activate, env and use tests. Breaking the implementation four ways (no legacy case, pathPolicy() starting from legacy, unknown values falling back to legacy, EmptyPath staying legacy) fails tests each time.

Docs

English and zh-hans. Quick Start and both READMEs lose the "set baseline" step and the announcement; they are identical to v1.0.13 again. The configuration guide described what legacy does as the general behavior; it now describes the default, and says how to keep the 1.0.x behavior (vfox config path.mode legacy, or path.preserve when a few directories have to stay in front). The FAQ says what can still win (pnpm, anything added after vfox activate) and what to check when vfox doctor still names a system directory (a shell started before the upgrade, legacy, path.preserve). AGENTS.md says where the default lives.

Not in this PR

• The release plan from Follow-ups of #736: plugin updates, the path.mode default and vfox config #737: which release, and whether to warn first with a vfox doctor notice. No release contains path.mode yet (v1.0.13 is the latest, main is three commits ahead), so the first release that has the setting can ship with baseline; there is no earlier release to warn in. If you would rather ship path.mode with legacy first and flip one release later, this PR can wait for that release.
• Release notes. GoReleaser builds them from PR titles. A draft to put first in the release is below.
• [BUG]: some of the packages are not changing accordingly #337 and [BUG]: On Windows, vfox use java@X doesn't change java when a JDK is in the system PATH and a global SDK is set #732 stay open until a release contains this.
• vfox config --unset path.mode still writes the default into the file instead of removing the key (Follow-ups of #736: plugin updates, the path.mode default and vfox config #737, item 4).

Draft for the release notes

Changed default: path.mode is baseline. vfox now puts its directories in front of whatever was in PATH when vfox activate ran, so the system's node or java (macOS path_helper, the Windows machine PATH) no longer hides the version you selected. What is added to PATH after activation, such as a virtualenv, still stays in front. To get the behavior of 1.0.x back, run vfox config path.mode legacy; to keep a few directories in front, list them in path.preserve. A shell that was started before the upgrade keeps the old order until you open a new terminal.

Verification

go test on all packages except internal/shared/printer (it needs a TTY), run on the exported tree of HEAD: pass. go vet on Linux, GOOS=windows and GOOS=darwin: clean. The docs site builds (VitePress, no dead links; the new callouts render in both languages).

On Windows most tests that exercise the PATH order skip, as before (they use POSIX paths, and the CLI fixture skips there, #737 item 5). The internal/config tests, which pin the default and its fallbacks, run there.

CI on my fork for the head commit (3703b90) is green: VersionFox CI (ubuntu, macOS, Windows, the Windows regressions, Fish) and vfox E2E Test (Unix, macOS, Windows, MSIX packaging): CI, E2E.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 51.39%. Comparing base (10c9f96) to head (3703b90).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #738   +/-   ##
=======================================
  Coverage   51.39%   51.39%           
=======================================
  Files         111      111           
  Lines        8240     8240           
=======================================
  Hits         4235     4235           
  Misses       3583     3583           
  Partials      422      422           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[linghengqian]

CC @aooohan . Could you please take a look and review this?