[linghengqian]

Seventeen commits, which can be read apart:

1. docs: add a page of scenarios, and say when .nvmrc is read
2. docs: say that Node.js 26 entered long-term support as Lithium (written before the fix and overtaken by 3 and 6, kept as it was pushed)
3. fix(parse_legacy_file): add Lithium (Node.js 26) to the codename table (the table is only the cold start since 14)
4. fix(parse_legacy_file): read a .nvmrc in UTF-16 or with a byte order mark
5. fix(parse_legacy_file): make vfox notice a version file after a cd
6. docs: describe Lithium, UTF-16 files and version files after a cd
7. docs: say what a build of vfox with the working directory in its state does (its message says 48 lines and the shell of docs/nvmrc.md; the patch adds 55 lines and the replayed shell is the one of docs/scenarios.md, see 9) (its text on the build is gone again with 13)
8. test: keep the hook tests from removing the state of the shell they run in
9. docs: keep the vfox patch in the repository, and say what it covers (taken out again by 13)
10. Merge origin/main into docs/use-case-scenarios: brings in fix: download with vfox's User-Agent so Huawei Cloud, TUNA, USTC and BFSU work as mirrors #45 (Huawei Cloud, TUNA, USTC and BFSU as mirrors). The only conflicts were the two "Unreleased" lists of docs/changes.md and docs/zh-CN/changes.md, where both pull requests added entries; both are kept, the one of fix: download with vfox's User-Agent so Huawei Cloud, TUNA, USTC and BFSU work as mirrors #45 first
11. docs: say that a second local run of the e2e suite can be a replay
12. test(e2e): wait for the Docker engine before the Windows suite pulls: Windows container (windows-latest) of the run for commit 11 failed because the Docker engine did not answer yet when run.ps1 started its base image pull (failed to connect to the docker API at npipe:////./pipe/docker_engine). Nothing in this pull request touches the Windows suite, and the two runs before on the same runner image passed, and the run for the commit itself passed in full
13. docs: take the vfox patch out of this pull request, and link the issues: the problem is reported in vfox as version-fox/vfox#745 and tracked here as Track version-fox/vfox#745: .nvmrc and .node-version are not applied after a cd #46, which stays open until a vfox release has the change. The patch of commits 7 and 9 is not part of the result of this pull request
14. fix(parse_legacy_file): learn the LTS lines from the index instead of a table: lts/<codename>, lts and lts/* no longer depend on a table that a release of the plugin has to extend for every line Node.js promotes. The plugin keeps what the index says in .lts-cache next to itself and reads it offline
15. test(e2e): check the file in which the plugin learned the LTS lines: the Linux and Windows suites read the file after the install and the search (the WSL suite follows in 17)
16. docs: say that the plugin learns the LTS lines from the index, English and Chinese
17. test(e2e): run the check of the learned LTS lines on WSL, and say what it shows on Windows: the WSL suite had not run the check of 15, although its verify.go asks to be changed together with the Linux one; and docs/e2e.md and a comment of the Windows suite said that the check tries a rename over an existing file, which the log does not show (see "Not checked")

The pull request began as the page of scenarios. Writing its cases turned up three problems of the plugin. They are fixed here, one commit each (3 to 5), so that any of them can be dropped, and 6 carries the documentation of all three, in both languages. The table of LTS codenames, which had gone stale for Lithium, no longer needs anybody to keep it up: the plugin learns the lines from the index (14 to 17).

The page of scenarios

docs/scenarios.md and docs/zh-CN/scenarios.md show the plugin in concrete cases, and both READMEs say what it is for: it does for vfox what nvm-sh/nvm does for POSIX shells, and it also works in PowerShell, where nvm-sh/nvm does not run. Cases: the nvm commands next to vfox's; Windows PowerShell 5.1 from scratch (execution policy, profile, what differs on Windows); one Node.js for a whole team (.vfox.toml, or the .nvmrc that nvm users already have, vfox install --all -y); several projects in one shell; another release in one window; vfox exec for a test matrix and for CI; following a line or pinning a release; mirrors and proxies; editors. Where release 0.5.3 and main differ, the tables show both, every cell taken from a run of each.

The fixes

LTS lines (3, 14). Node.js 26 entered long-term support on 2026-10-28 as Lithium. The codename table ended at Krypton, so under latest_installed lts/lithium selected nothing and lts and lts/* selected a 24.x, while latest_available selected 26.13.0. Commit 3 added lithium = 26, which is the stopgap that a table needs once a year. ParseLegacyFile runs at every prompt in a directory with a version file, so it cannot ask the index for the lines: 336 KB, and two requests for an lts/ name, which took 750 to 1000 ms a prompt against 10 ms (measured with a logging mirror, nodejs.org from here; 270 to 380 ms through npmmirror). Commit 14 has the plugin write what the index says into .lts-cache, a text file next to the plugin where vfox keeps its own .available.cache, whenever it has the index in hand anyway: Available (vfox search, an install of latest or of a major), and an install of an exact release when the file is missing or a day old (vfox installs those without asking Available). ParseLegacyFile reads the file, over the built-in table, and never fetches. A plugin directory that cannot be written, or a plugin that has learned nothing yet, has the table, as before. nvm and fnm read the index; asdf-nodejs, whose logic this was taken from, still ends its table at Krypton. The built-in table is the cold start, and a line missing from it is learned the first time the plugin has the index in hand.

UTF-16 and a byte order mark (4). Windows PowerShell 5.1 writes UTF-16 with a mark for > and Out-File, and UTF-8 with a mark for -Encoding UTF8. The plugin read the bytes as they were, so the mark became part of the text, no release matched it, and vfox said nothing. util.decode_text decodes both, and leaves text with no mark as it is. UTF-32 and UTF-16 without a mark are still not read, and the docs say so.

A .nvmrc after a cd (5), a workaround. vfox 1.0.13 keeps the result of vfox env for a shell (env-state.json in the session directory) and calculates again only for another .vfox.toml, a changed PATH or a newer config file. A .nvmrc or .node-version is not among these, and main of vfox has the same code (internal/env/state.go, and configPaths in cmd/commands/env.go holds only .vfox.toml files that exist). So after a cd from a running shell the file was ignored. vfox runs ParseLegacyFile before it loads that state, and the hook now removes env-state.json whenever it reads a version file (util.forget_env_state). What that does and does not do, with the same shell replayed under release 0.5.3 and under this branch (global release 26.13.0):

Step	Release 0.5.3	This branch
cd into a directory with a .nvmrc for 18.20.8	v26.13.0	v18.20.8
cd into a directory with a .node-version for 24.22.2	v26.13.0	v24.22.2
edit that file to name 22.23.4	v26.13.0	v22.23.4
cd into a directory with no config at all	v26.13.0	v22.23.4
cd into a directory with a .vfox.toml for 18.20.8	v18.20.8	v18.20.8
cd into a directory with no config at all	v26.13.0	v26.13.0

• It does not fix the way out. In a directory with no config at all the hook is not called, so vfox keeps the result of the directory that was left and the shell stays on its release (the bold cell). A directory with a .vfox.toml or a version file of its own switches, and so does a new shell. I found no way to do that from a plugin, and it needs a change in vfox. It is reported there as version-fox/vfox#745 (a reproduction with the 1.0.13 release and with main, the cause, two ways to change it) and tracked here as Track version-fox/vfox#745: .nvmrc and .node-version are not applied after a cd #46. A change that ties vfox's kept result to the working directory, which I tried on 1.0.13, switched on every cd of the shell above, the way out included, with the plugin of this branch and with release 0.5.3; it does not notice an edit of the file in the directory the shell is in (release 0.5.3 stayed on the old release), so commit 5 would stay useful for that. The patch itself is not part of this pull request.
• It reaches into a file that vfox owns, by its name and by $__VFOX_CURTMPPATH, and it makes vfox calculate again at every prompt in a directory with a version file. The extra calculation took about a millisecond per prompt with one SDK installed (7.4 against 7.6 ms for vfox env, 30 calls each), and with many SDKs it will cost more. It is isolated in one function and one call, so dropping commit 5 is a revert, plus the lines of commit 6 that describe it. Say so if you would rather not carry it.

How it was checked

• Hook tests: 73 pass (the 63 of this branch before fix: download with vfox's User-Agent so Huawei Cloud, TUNA, USTC and BFSU work as mirrors #45, the 2 of fix: download with vfox's User-Agent so Huawei Cloud, TUNA, USTC and BFSU work as mirrors #45 and 8 for the LTS lines; 53 before this pull request), and the first three code commits pass at every step (55, 59, 63). Each of 12 mutations of the LTS code, made in a copy (what was learned ignored, the table winning over it, a stale or fresh file misjudged, no refresh at an install, the refresh before the install is checked, no rename, a Windows path without its backslash, a damaged line trusted, and others), turns one of them red. Commit 8 fixes a side effect of commit 5 that I found by running them in a shell where vfox is active: forget_env_state removed the env-state.json of that shell, since the tests used the real os.getenv and os.remove. CI has no such shell, so it did not show. The tests now hide __VFOX_CURTMPPATH, and with it set the file survives a run. StyLua 2.5.2 --check . and LuaLS 3.19.1 --checklevel=Warning are clean, with the release assets checked against the digests that GitHub publishes. gofmt, go vet (also GOOS=windows for the Windows suite) and go test -short in tests/e2e pass.
• Against the real vfox 1.0.13, in a scratch HOME with a clean environment: the .nvmrc encodings (ASCII with LF, CRLF or no line break, UTF-8 with a mark, UTF-16 in both byte orders), lts/lithium, lts/* and lts under the three strategies, and the shell above in bash 5.3 and in PowerShell 7.6.9 (the official linux-x64 tarball, SHA-256 checked), calling the prompt function that the hook installs once per command. --debug shows Config changed: true in a directory with a version file and Using cached output after leaving it.
• The LTS lines against the real vfox 1.0.13, in a scratch HOME: vfox search wrote .lts-cache with the twelve lines of the live index, equal to the built-in table, and left no temporary file. With a local mirror whose index has an invented v28.0.0, Mercury, a fake 28.0.0 installed and lts/mercury in a .nvmrc, latest_installed selects it and the prompts made no request; without the file it selects nothing. A PreInstall of 20.20.2 fetched the index once and not on the second run. gopher-lua 1.1.1 ends in a Go nil pointer dereference at if file == nil after local file = path ~= nil and io.open(path, "r") or nil; the code opens the file in two statements, and docs/development.md says so.
• The e2e suite on Linux, glibc, vfox latest, default mirror, run locally with E2E_MAX_JOBS=1: pass, including the legacy probes and the new check of .lts-cache (commit 15; 208 s with -count=1), before the merge and again on the merge of main (78 s with -count=1). The first run on the merge printed ok ... (cached) with the timings of the run before it, because go test replays a result when what the test opened looks unchanged, plugin files that had changed included. I threw that run away and ran it again with -count=1; commit 11 says so in docs/e2e.md. The rest of the matrix ran in CI, see the next item.
• The E2E workflow in the run for 28736b7 (run 41628376081): every job passed, and so did the other checks (check, license-eye, lint-go, lint-lua, test). The check of .lts-cache (commits 15 and 17) printed PASS the plugin learned 12 LTS lines from the index, the newest is 26 for all 17 combinations: Linux and Alpine on amd64 and arm64 (latest and main vfox with the default mirror, and latest with npmmirror on amd64), windows-latest (three), windows-11-arm (two) and WSL (two). In the Windows containers the plugin is in C:\Users\John Doe\.vfox\plugin\nodejs, with a space in the path, and Get-Content found the file there with all twelve codenames at the majors of the table, so on Windows the plugin finds its directory and writes to it. The run for 0c69b48, before commit 17, passed the same way on every job except WSL, which did not run the check yet.
• The reproduction in version-fox/vfox#745, run in a scratch HOME with a clean environment and the nodejs plugin 0.5.3 from the registry (vfox add nodejs), with the 1.0.13 release binary and with a build of main (cdf0747): two bash sessions, one that goes into a .nvmrc directory and one that goes out of it. The output is identical for both, and the transcripts in the issue are that output. The seven-step shell of docs/scenarios.md ran on that build of main too, with release 0.5.3 of the plugin and with the plugin of this branch, and gave the same cells as with 1.0.13; the row of the table above that edits the file was only run on 1.0.13.
• Every relative link and heading anchor resolves, in all 30 pages after the merge, and the English and Chinese scenarios.md have the same code blocks and the same inline code.

Not checked

• Whether the wait for the Docker engine (commit 12) is what fixes the failure. The wait ran on Windows in the run for commit 12 and every job passed, but nothing in the log says whether the engine was slow this time. That it was slow in the failed run is read from the log and the timings, not reproduced. The function itself was also run with PowerShell 7.6.9 on Linux against a fake docker (an engine that answers at once, on the third call, never, and no docker).
• A write over an existing .lts-cache on Windows (commits 14 and 15). The Windows jobs show that the plugin finds its directory and writes there, see above. They do not show that a write replaces a file that is already there: by the order of the steps the install writes the file and the search writes it again, but a rename that failed the second time would leave the first file, and the check passes with that file too. The plugin takes it quietly, since the file would stay as old as the first write and an install after a day would fetch the index again, with no other harm. The only basis for it working is that Go's os.Rename, which os.rename calls under gopher-lua, replaces an existing file on Windows. My first text for docs/e2e.md and a comment in the Windows suite said that the check tries this rename; commit 17 takes that back.
• A cd in a running Windows shell. The Windows suite writes the pinned version with -Encoding Unicode and utf8BOM and probes both, and no longer removes env-state.json itself before a probe, so it relies on commit 5. Those probes passed on windows-latest (three combinations) and windows-11-arm (two) in the run for commit 12, and the two runs before it succeeded as well. But each probe starts a new PowerShell, so none of this is a cd in a shell that keeps running, which is what forget_env_state is for, and it does not show that the file is removed on Windows paths (a removal that fails is ignored on purpose). PowerShell 7 writes the same bytes for these encodings as Windows PowerShell 5.1 does for > and -Encoding UTF8 (checked on Linux).
• Windows PowerShell 5.1 itself. The e2e suite never runs it. The statements about its execution policy and about what it writes rest on Microsoft's documentation, and the ones about the registry Path, junctions, the fallback to the global scope and vfox exec with node.exe rest on vfox's source. docs/scenarios.md marks each.
• vfox's documentation says a bare vfox use is global on Windows. Its source defaults to the session when the hook is active. The pages spell out the scope in every Windows command.