[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 baseline mode, the default, so upgrading does not reorder the PATH of a shell that is already running. It gets the new default when it is restarted. aggressive never reads the baseline and demotes the same entries with or without one. TestEnvWithoutABaselineOnlyBaselineModeFallsBackToLegacy covers the unconfigured case and each of the modes.
• 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 55.58%. Comparing base (37cff8f) to head (7394477).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #738   +/-   ##
=======================================
  Coverage   55.58%   55.58%           
=======================================
  Files         112      112           
  Lines        8448     8448           
=======================================
  Hits         4696     4696           
  Misses       3293     3293           
  Partials      459      459           

☔ 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?

[linghengqian]

CC @version-fox/vfox-maintainers @version-fox/vfox-committers . Could you please take a look and review this?

[Copilot]

🟡 Changes recommended

AGENTS.md overstates legacy compatibility by omitting that aggressive mode still demotes certain entries when __VFOX_ORIG_PATH is absent.

1 open issue

• Clarify missing-baseline behavior for aggressive mode · New

What changed in this PR

This pull request changes the default path.mode from legacy to baseline, putting vfox-managed SDK paths ahead of inherited PATH entries while preserving paths added after activation. It updates configuration behavior, diagnostics, tests, documentation, and migration guidance.

Changes:

• Centralizes baseline as the default path mode while preserving explicit legacy behavior.
• Updates PATH-policy, activation, cache, diagnostic, CLI, and configuration tests.
• Revises English and Chinese documentation and repository guidance for the new default.

File	Description
README.md	Removes the manual baseline configuration step.
README_CN.md	Removes the corresponding Chinese configuration step.
internal/​sdk/​check.go	Updates PATH shadow diagnostics for legacy mode.
internal/​sdk/​check_test.go	Tests diagnostics under default, baseline, and legacy modes.
internal/​env/​pathpolicy.go	Uses the centralized default PATH mode.
internal/​env/​pathpolicy_test.go	Updates PATH ordering and policy-cache coverage.
internal/​env/​context.go	Documents baseline as the default mode.
internal/​config/​path.go	Defines the baseline default and updates mode fallbacks.
internal/​config/​path_test.go	Verifies defaults, fallbacks, merging, and serialization.
internal/​config/​new_file_test.go	Tests new-file and shared-configuration behavior.
docs/​zh-hans/​guides/​quick-start.md	Removes obsolete baseline setup instructions.
docs/​zh-hans/​guides/​faq.md	Updates Chinese PATH-shadowing guidance.
docs/​zh-hans/​guides/​configuration.md	Documents the new default and legacy compatibility option.
docs/​guides/​quick-start.md	Removes obsolete baseline setup instructions.
docs/​guides/​faq.md	Updates PATH-shadowing explanations and troubleshooting.
docs/​guides/​configuration.md	Documents baseline as the default and explains legacy migration.
cmd/​commands/​path_cli_test.go	Tests CLI PATH behavior for default, baseline, and legacy modes.
cmd/​commands/​doctor_cli_test.go	Updates shadow-diagnostic coverage.
cmd/​commands/​config_cli_test.go	Updates configuration and shared-setting tests.
cmd/​commands/​alias_cli_test.go	Verifies alias changes preserve non-default shared settings.
AGENTS.md	Updates guidance for the baseline default; one statement should be scoped to baseline mode because aggressive mode behaves differently without a recorded baseline.

_{Review effort: Lite}