diff --git a/README.md b/README.md
index 53a9e30..35daf9a 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,18 @@ Java plugin for [vfox](https://vfox.dev/).
 
 It installs JDKs from 31 distributions, among them Temurin, Zulu, Liberica, Corretto, Microsoft and GraalVM, looked up through [Foojay](https://foojay.io/). On Linux loong64 it installs from the Loongnix archive instead.
 
+## Use cases
+
+The plugin installs several JDKs side by side and switches between them for one shell, for a project or for every new shell, which is what [SDKMAN](https://sdkman.io/) does. It also works where SDKMAN does not. SDKMAN is a set of bash scripts, so on Windows it needs WSL or Git Bash and cannot be used in PowerShell, not even in the Windows PowerShell 5.1 that comes with Windows, while vfox is a native program with a hook for PowerShell. There the plugin takes SDKMAN's place. It follows SDKMAN's short names and reads `.sdkmanrc`, so SDKMAN users and vfox users can share a project. The commands side by side:
+
+| | SDKMAN | vfox |
+| --- | --- | --- |
+| Install | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
+| Use in the current shell only | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
+| Use in every new shell | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |
+
+See [docs/sdkman.md](docs/sdkman.md) for when to use the plugin, the other commands and what differs.
+
 ## Install
 
 After installing [vfox](https://github.com/version-fox/vfox), install the plugin by running:
diff --git a/README_CN.md b/README_CN.md
index 5a7d4bf..5ce57da 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -6,6 +6,18 @@
 
 它通过 [Foojay](https://foojay.io/) 查找并安装 31 个发行版的 JDK，包括 Temurin、Zulu、Liberica、Corretto、Microsoft、GraalVM 等。在 Linux loong64 上，则改从 Loongnix 归档安装。
 
+## 适用场景
+
+这个插件可以同时装好几个 JDK，并按单个 Shell、按项目，或为之后新开的所有 Shell 切换，[SDKMAN](https://sdkman.io/) 做的就是这件事。它还能用在 SDKMAN 用不了的地方：SDKMAN 是一组 bash 脚本，在 Windows 上要借助 WSL 或 Git Bash，不能在 PowerShell 里使用，Windows 自带的 Windows PowerShell 5.1 也不行；vfox 是原生的 Windows 程序，能挂载到 PowerShell，在那里这个插件就取代了 SDKMAN。插件沿用 SDKMAN 的简称，也读取 `.sdkmanrc`，所以 SDKMAN 用户和 vfox 用户可以共用同一个项目。两边的命令对照如下：
+
+| | SDKMAN | vfox |
+| --- | --- | --- |
+| 安装 | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
+| 只在当前 Shell 里使用 | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
+| 在之后新开的所有 Shell 里使用 | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |
+
+什么时候该用这个插件、其余的命令以及它们的差别，见 [docs/zh-CN/sdkman.md](docs/zh-CN/sdkman.md)。
+
 ## 安装
 
 先安装 [vfox](https://github.com/version-fox/vfox)，然后执行下面的命令安装插件：
diff --git a/docs/sdkman.md b/docs/sdkman.md
new file mode 100644
index 0000000..2f7810c
--- /dev/null
+++ b/docs/sdkman.md
@@ -0,0 +1,48 @@
+# SDKMAN and vfox
+
+[中文](zh-CN/sdkman.md) | [English](sdkman.md)
+
+[SDKMAN](https://sdkman.io/) installs JDKs and switches between them with `sdk install java` and `sdk use java`. With this plugin vfox does the same. It follows SDKMAN's short names and reads its `.sdkmanrc`, so much of what you know from SDKMAN carries over. This page says when to use the plugin, puts the commands side by side and lists what differs.
+
+## When to use it
+
+- **You work in Windows PowerShell.** SDKMAN is a set of bash scripts. Its [installation page](https://sdkman.io/install) says that it requires a bash environment and cannot be installed natively on Windows: it runs in WSL, or in Git Bash with MinGW. That leaves out PowerShell, including the Windows PowerShell 5.1 that comes with Windows, and cmd. vfox is a native Windows program with a hook for PowerShell, so `vfox install java@21-tem` and `vfox use` work there without WSL or Git Bash. This is where the plugin takes SDKMAN's place.
+- **Your shell is not Bash or Zsh.** SDKMAN supports those two. vfox hooks into Bash, Zsh, Fish, PowerShell, Nushell and Clink, see its [quick start](https://vfox.dev/guides/quick-start.html).
+- **A team or a set of scripts spans systems.** The commands are the same on Linux, macOS and Windows. A project's `.sdkmanrc` is read through the plugin, so developers on SDKMAN and developers on vfox can share it, see [sdkmanrc.md](sdkmanrc.md).
+- **You manage more than JDKs.** vfox has plugins for Maven, Gradle, Groovy, Kotlin, Scala, Node.js, Go and many other tools behind the same commands (`vfox available`).
+
+If you work in Bash or Zsh on Linux or macOS and SDKMAN does what you need, there is no reason to change.
+
+## Commands side by side
+
+The examples use Temurin 21.0.8. Both tools have to be hooked into the shell first: SDKMAN by sourcing `sdkman-init.sh`, vfox by `vfox activate`, see its [quick start](https://vfox.dev/guides/quick-start.html). The vfox commands are the same in every shell it hooks into.
+
+| | SDKMAN | vfox |
+| --- | --- | --- |
+| Install | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
+| List what can be installed | `sdk list java` | `vfox search java tem`, `vfox search java all` for every distribution |
+| List what is installed | `sdk list java` marks them | `vfox list java` |
+| Use in the current shell only | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
+| Use in every new shell | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |
+| Pin a project | `sdk env init` writes a `.sdkmanrc` with the JDK in use | `vfox use --project java@21.0.8-tem` writes a `.vfox.toml` |
+| Switch to the project's JDK | `sdk env`, or on every `cd` with `sdkman_auto_env=true` | automatic, by the hook, on entering the directory |
+| Install the project's JDKs | `sdk env install` | `vfox install --all` for a `.vfox.toml`, nothing for a `.sdkmanrc` |
+| Show the JDK in use | `sdk current java` | `vfox current java` |
+| Show where a JDK is | `sdk home java 21.0.8-tem` | `vfox info java@21.0.8+9-tem` |
+| Uninstall | `sdk uninstall java 21.0.8-tem` | `vfox uninstall java@21.0.8+9-tem` |
+| See which JDKs are outdated | `sdk upgrade java` | none, compare `vfox list java` with `vfox search java tem` |
+| Update the tool | `sdk selfupdate` | `vfox upgrade`, and `vfox update java` for this plugin |
+| Show the version of the tool | `sdk version` | `vfox --version` |
+
+The scopes of `vfox use` correspond to SDKMAN's: `--session`, the default, to `sdk use`, `--global` to `sdk default` and `--project` to a `.sdkmanrc`. Without vfox's hook, `vfox use` stops on Linux and macOS and falls back to the global scope on Windows, see [versions.md](versions.md#using).
+
+## What differs
+
+- **Identifiers.** SDKMAN's `21.0.8-tem` goes after `java@` as it is, and the short names are SDKMAN's, with a few exceptions such as `jb`, which SDKMAN calls `jbr`, see [distributions.md](distributions.md#short-names-and-sdkman). A release padded with a zero, as in SDKMAN's current identifiers (`25.0.5.0+8-tem`), is accepted. JavaFX is `-fx` at the end, `21.0.12-zulu-fx`. SDKMAN's `21.0.12.fx-zulu` is not a spec that `vfox install` takes, though a `.sdkmanrc` can hold it, see [sdkmanrc.md](sdkmanrc.md#sdkmans-spellings).
+- **A bare major.** `vfox install java@21-tem` installs the newest Temurin 21, `21.0.13+9-tem` on 2026-11-02. SDKMAN's `21-tem` is one release, the GA build `21+35`.
+- **No default JDK.** `sdk install java` installs SDKMAN's default, a Temurin LTS release (`25.0.5.0+8-tem` on 2026-11-02). `vfox install java` has none: in a terminal it asks you to pick a version, in a script it fails. A version without a distribution (`java@21`) is OpenJDK from jdk.java.net, which has nothing newer than 21.0.2 for 21. Write `java@21-tem`, see [versions.md](versions.md#without-a-distribution).
+- **Installing does not select.** After `sdk install`, SDKMAN asks whether the JDK becomes the default. `vfox install` only installs, and `vfox use` selects.
+- **Two lists.** `sdk list java` shows every vendor's JDKs. `vfox search java` lists OpenJDK only, so name a distribution (`vfox search java tem`) or write `all`. `vfox list java` shows what is installed. The versions come from [Foojay](foojay.md).
+- **Installed names carry the build number.** `vfox list java` shows `21.0.8+9-tem`, which `vfox uninstall` and `vfox info` need in full, while `vfox use java@21.0.8-tem` finds it without the build, see [versions.md](versions.md#installed-names).
+- **A `.sdkmanrc` only selects.** `sdk env install` installs the JDKs it names. The plugin selects among the installed ones, see [sdkmanrc.md](sdkmanrc.md#differences-from-sdkman).
+- **Where the JDKs are.** SDKMAN keeps them in `~/.sdkman/candidates/java/<identifier>`. vfox keeps them in `~/.vfox/cache/java/v-<name>/java-<name>` and makes `JAVA_HOME` a link to the one you chose. `vfox info` prints the directory that holds `java-<name>`. IntelliJ IDEA finds the JDKs of SDKMAN by itself but lists only the JDK in use of vfox, see [troubleshooting.md](troubleshooting.md#where-the-jdk-is).
diff --git a/docs/sdkmanrc.md b/docs/sdkmanrc.md
index e4d04bc..0073138 100644
--- a/docs/sdkmanrc.md
+++ b/docs/sdkmanrc.md
@@ -81,4 +81,4 @@ If the JDK does not switch:
 
 ## Differences from SDKMAN
 
-`sdk env install` installs the JDKs a `.sdkmanrc` names. vfox only selects among what is installed, and you install with `vfox install java@<version>`. An identifier copied from the file is not always a spec that `vfox install` takes: `21.0.8-tem` is, `21.0.12.fx-zulu` is not, and `21.0.12-zulu-fx` is.
+`sdk env install` installs the JDKs a `.sdkmanrc` names. vfox only selects among what is installed, and you install with `vfox install java@<version>`. An identifier copied from the file is not always a spec that `vfox install` takes: `21.0.8-tem` is, `21.0.12.fx-zulu` is not, and `21.0.12-zulu-fx` is. [sdkman.md](sdkman.md) puts the other commands of the two tools side by side.
diff --git a/docs/zh-CN/sdkman.md b/docs/zh-CN/sdkman.md
new file mode 100644
index 0000000..55eac5c
--- /dev/null
+++ b/docs/zh-CN/sdkman.md
@@ -0,0 +1,48 @@
+# SDKMAN 与 vfox
+
+[中文](sdkman.md) | [English](../sdkman.md)
+
+[SDKMAN](https://sdkman.io/) 用 `sdk install java` 和 `sdk use java` 安装并切换 JDK。有了这个插件，vfox 也能做同样的事。插件沿用 SDKMAN 的简称，也能读取它的 `.sdkmanrc`，所以你在 SDKMAN 上积累的经验大多可以直接用。本页说明什么时候该用这个插件，把两边的命令并列出来，并列出它们的差别。
+
+## 什么时候用
+
+- **你在 Windows PowerShell 里工作。** SDKMAN 是一组 bash 脚本。它的[安装页面](https://sdkman.io/install)写明它需要 bash 环境，在 Windows 上不能原生安装：只能在 WSL 里，或者在带 MinGW 的 Git Bash 里运行。所以 PowerShell（包括 Windows 自带的 Windows PowerShell 5.1）和 cmd 都用不了它。vfox 是原生的 Windows 程序，能挂载到 PowerShell，所以 `vfox install java@21-tem` 和 `vfox use` 在那里直接可用，不需要 WSL 或 Git Bash。在这里，这个插件取代了 SDKMAN。
+- **你用的不是 Bash 或 Zsh。** SDKMAN 只支持这两种。vfox 可以挂载到 Bash、Zsh、Fish、PowerShell、Nushell 和 Clink，见它的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。
+- **团队或脚本要跨系统。** Linux、macOS 和 Windows 上的命令一样。项目里的 `.sdkmanrc` 会通过插件读取，所以用 SDKMAN 的开发者和用 vfox 的开发者可以共用它，见 [sdkmanrc.md](sdkmanrc.md)。
+- **你管理的不只是 JDK。** vfox 有 Maven、Gradle、Groovy、Kotlin、Scala、Node.js、Go 等许多工具的插件，用的是同一套命令（`vfox available`）。
+
+如果你在 Linux 或 macOS 上用 Bash 或 Zsh，而 SDKMAN 已经满足需要，就没有换的理由。
+
+## 命令对照
+
+示例用 Temurin 21.0.8。两个工具都要先挂载到 Shell：SDKMAN 是 source `sdkman-init.sh`，vfox 是 `vfox activate`，见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。vfox 的命令在它能挂载的所有 Shell 里都一样。
+
+| | SDKMAN | vfox |
+| --- | --- | --- |
+| 安装 | `sdk install java 21.0.8-tem` | `vfox install java@21.0.8-tem` |
+| 列出可安装的版本 | `sdk list java` | `vfox search java tem`；`vfox search java all` 列出所有发行版 |
+| 列出已安装的版本 | `sdk list java` 会标出已安装的 | `vfox list java` |
+| 只在当前 Shell 里使用 | `sdk use java 21.0.8-tem` | `vfox use java@21.0.8-tem` |
+| 在之后新开的所有 Shell 里使用 | `sdk default java 21.0.8-tem` | `vfox use --global java@21.0.8-tem` |
+| 为项目固定版本 | `sdk env init` 写出带有当前 JDK 的 `.sdkmanrc` | `vfox use --project java@21.0.8-tem` 写出 `.vfox.toml` |
+| 切换到项目的 JDK | `sdk env`，或设置 `sdkman_auto_env=true` 后每次 `cd` 自动切换 | 挂载之后，进入目录时自动切换 |
+| 安装项目要的 JDK | `sdk env install` | `.vfox.toml` 用 `vfox install --all`，`.sdkmanrc` 没有对应的命令 |
+| 查看正在使用的 JDK | `sdk current java` | `vfox current java` |
+| 查看 JDK 在哪里 | `sdk home java 21.0.8-tem` | `vfox info java@21.0.8+9-tem` |
+| 卸载 | `sdk uninstall java 21.0.8-tem` | `vfox uninstall java@21.0.8+9-tem` |
+| 查看哪些 JDK 过时了 | `sdk upgrade java` | 没有，自己对比 `vfox list java` 和 `vfox search java tem` |
+| 升级工具本身 | `sdk selfupdate` | `vfox upgrade`；插件用 `vfox update java` |
+| 查看工具的版本 | `sdk version` | `vfox --version` |
+
+`vfox use` 的作用域与 SDKMAN 的命令对应：默认的 `--session` 对应 `sdk use`，`--global` 对应 `sdk default`，`--project` 对应 `.sdkmanrc`。没有挂载 vfox 时，`vfox use` 在 Linux 和 macOS 上会报错退出，在 Windows 上则退到全局作用域，见 [versions.md](versions.md#使用)。
+
+## 差别
+
+- **标识符。** SDKMAN 的 `21.0.8-tem` 原样写在 `java@` 后面，简称也沿用 SDKMAN 的，只有少数例外，比如 JetBrains Runtime 在 SDKMAN 里叫 `jbr`，这里是 `jb`，见 [distributions.md](distributions.md#简称与-sdkman-的不同)。SDKMAN 现在的标识符会给版本补一个零（`25.0.5.0+8-tem`），这样的写法也能识别。JavaFX 是放在最后的 `-fx`，即 `21.0.12-zulu-fx`。SDKMAN 的 `21.0.12.fx-zulu` 不是 `vfox install` 接受的写法，不过 `.sdkmanrc` 里可以写，见 [sdkmanrc.md](sdkmanrc.md#sdkman-的写法)。
+- **只写大版本号。** `vfox install java@21-tem` 装的是最新的 Temurin 21，2026-11-02 是 `21.0.13+9-tem`。SDKMAN 的 `21-tem` 只是一个版本，即 GA 构建 `21+35`。
+- **没有默认 JDK。** `sdk install java` 装的是 SDKMAN 的默认版本，一个 Temurin 的 LTS 版本（2026-11-02 是 `25.0.5.0+8-tem`）。`vfox install java` 没有默认值：在终端里它会让你选一个版本，在脚本里则直接失败。只写版本不写发行版（`java@21`）指的是 jdk.java.net 上的 OpenJDK，它的 21 只到 21.0.2。请写 `java@21-tem`，见 [versions.md](versions.md#不写发行版)。
+- **安装不等于选中。** `sdk install` 之后，SDKMAN 会问要不要把这个 JDK 设为默认。`vfox install` 只负责安装，选中要用 `vfox use`。
+- **两份列表。** `sdk list java` 列出所有厂商的 JDK。`vfox search java` 只列 OpenJDK，所以要写上发行版（`vfox search java tem`）或 `all`。已安装的看 `vfox list java`。版本数据来自 [Foojay](foojay.md)。
+- **安装后的版本名带构建号。** `vfox list java` 显示 `21.0.8+9-tem`，`vfox uninstall` 和 `vfox info` 都要写全，而 `vfox use java@21.0.8-tem` 不写构建号也能找到它，见 [versions.md](versions.md#安装后的版本名)。
+- **`.sdkmanrc` 只负责选中。** `sdk env install` 会安装它里面写的 JDK。插件只在已安装的 JDK 里选，见 [sdkmanrc.md](sdkmanrc.md#与-sdkman-的区别)。
+- **JDK 在哪里。** SDKMAN 把 JDK 放在 `~/.sdkman/candidates/java/<标识符>`。vfox 放在 `~/.vfox/cache/java/v-<版本名>/java-<版本名>`，`JAVA_HOME` 是指向你所选 JDK 的链接。`vfox info` 打印的是包含 `java-<版本名>` 的那个目录。IntelliJ IDEA 能自己找到 SDKMAN 的 JDK，但对 vfox 只会列出正在使用的那个，见 [troubleshooting.md](troubleshooting.md#jdk-在哪里)。
diff --git a/docs/zh-CN/sdkmanrc.md b/docs/zh-CN/sdkmanrc.md
index 809bd9a..28bb8b5 100644
--- a/docs/zh-CN/sdkmanrc.md
+++ b/docs/zh-CN/sdkmanrc.md
@@ -81,4 +81,4 @@ JDK 没有切换时，依次检查：
 
 ## 与 SDKMAN 的区别
 
-`sdk env install` 会安装 `.sdkmanrc` 里指明的 JDK。vfox 只在已安装的版本里选择，安装要用 `vfox install java@<版本>`。从文件里复制的标识符不一定能直接给 `vfox install` 用：`21.0.8-tem` 可以，`21.0.12.fx-zulu` 不行，`21.0.12-zulu-fx` 可以。
+`sdk env install` 会安装 `.sdkmanrc` 里指明的 JDK。vfox 只在已安装的版本里选择，安装要用 `vfox install java@<版本>`。从文件里复制的标识符不一定能直接给 `vfox install` 用：`21.0.8-tem` 可以，`21.0.12.fx-zulu` 不行，`21.0.12-zulu-fx` 可以。两个工具其余的命令对照见 [sdkman.md](sdkman.md)。