From 2446587a5631b30c1a57005ac037f05391ce4c95 Mon Sep 17 00:00:00 2001
From: {{Your Name}} <{{your.email@example.com}}>
Date: Thu, 7 May 2026 12:52:51 -0700
Subject: [PATCH] docs: add JDK resolution strategy section to README

Document the three-tier JDK resolution cascade (local discovery,
default version upgrade, highest available fallback), version syntax,
provider ordering, and key behaviors.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 5945f76..256b5b3 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,50 @@ See:
 jvm --help
 ```
 
+## JDK Resolution Strategy
+
+`jvm` delegates JDK discovery and installation to the [devkitman](https://github.com/jbangdev/jbang-devkitman) library. When you request a Java version (e.g. `jvm install 17`), resolution follows a three-tier cascade:
+
+### Version Syntax
+
+- `17` — interpreted as `17+`, meaning version 17 **or newer** (open-ended)
+- `17!` — **exact** major version 17 only
+- `temurin-21.0.3` — a provider-specific JDK identifier (matched by ID, not version)
+
+### Tier 1 — Local Discovery
+
+Providers are queried in fixed registration order:
+
+1. `current` — the JDK running the current process
+2. `default` — the JDK set as the global default (`~/.jbang/currentjdk` symlink)
+3. `javahome` — the JDK pointed to by `JAVA_HOME`
+4. `path` — the JDK found on `PATH`
+5. `linked` — manually linked JDK installations
+6. `jbang` — JBang-managed JDKs (supports install/uninstall)
+7. Platform-specific providers (`multihome`, `sdkman`, `scoop`, `brew`, `mise`, `linux`)
+
+The **first provider** that returns a matching installed JDK wins. There is no cross-provider sorting or "pick the best version" logic — provider priority alone determines the result.
+
+Run `jvm list-providers` to see which providers are active on your system.
+
+### Tier 2 — Default Version Upgrade
+
+When no installed JDK satisfies the request and the request is **open-ended below version 21** (the configured default), the system redirects to version 21 instead of downloading the minimum satisfying version. For example, `jvm install 11` (interpreted as `11+`) with no local JDKs available will install JDK 21, not 11.
+
+Exact requests bypass this: `jvm install 11!` will always install exactly version 11.
+
+### Tier 3 — Highest Available Fallback
+
+If the default version itself cannot be resolved (e.g. the download API doesn't offer it), the system aggregates all downloadable JDKs from all installable providers, filters by the original minimum version, and selects the **highest available**.
+
+### Key Behaviors
+
+- **Installed JDKs always take priority** over downloads, regardless of version
+- **Open-ended requests get upgraded** to the default version (21) when nothing is installed locally
+- **Exact requests are honored literally** — no version upgrading occurs
+- **Installation is lazy** — resolution may identify a downloadable JDK without downloading it until explicitly needed
+- **The `.jvmrc` file** in the current directory (or home directory) can specify a default version via `java=<version>`, used when no version argument is provided
+
 ## Development
 
 To build the project simply run: