Reverted toolbox to jdk 21, fixed comments and docs (#852)

Co-authored-by: Lee Wexler <lbwexler@xh.io>

Author: jskupsik

.github/workflows/buildRelease.yml

@@ -73,10 +73,10 @@ jobs:
         steps:
         - uses: actions/checkout@v6
 
-        - name: Setup JDK 25
+        - name: Setup JDK 21
           uses: actions/setup-java@v5
           with:
-              java-version: '25'
+              java-version: '21'
               distribution: 'zulu'
 
         - name: Setup Gradle

.github/workflows/buildSnapshot.yml

@@ -44,10 +44,10 @@ jobs:
         steps:
         - uses: actions/checkout@v6
 
-        - name: Setup JDK 25
+        - name: Setup JDK 21
           uses: actions/setup-java@v5
           with:
-              java-version: '25'
+              java-version: '21'
               distribution: 'zulu'
 
         - name: Setup Gradle

.github/workflows/ci.yml

@@ -21,10 +21,10 @@ jobs:
 
         steps:
         - uses: actions/checkout@v6
-        - name: Setup JDK 25
+        - name: Setup JDK 21
           uses: actions/setup-java@v5
           with:
-              java-version: '25'
+              java-version: '21'
               distribution: 'zulu'
 
         - name: Setup Gradle
@@ -87,10 +87,10 @@ jobs:
 
         steps:
         - uses: actions/checkout@v6
-        - name: Setup JDK 25
+        - name: Setup JDK 21
           uses: actions/setup-java@v5
           with:
-              java-version: '25'
+              java-version: '21'
               distribution: 'zulu'
 
         # Generates and submits a dependency graph, enabling Dependabot Alerts for all project dependencies.

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 9.0-SNAPSHOT - unreleased
 
+* Downgraded toolbox build toolchain back to JDK 21 — JDK 25 is not currently usable out of the box (Gradle 8.x caps its compatible JVM at version 24) and requires advanced setup not recommended for most production apps.
+* Added a `majorJavaVersion` property to `gradle.properties` to centralize JVM version control, this is a good pattern to have in client apps.
+
 ## 8.4.0 - 2026-04-30
 
 ### Libraries

CLAUDE.md

@@ -194,8 +194,8 @@ additional setup required — it runs directly from installed `node_modules`. Se
 A Groovy-based MCP server exposing hoist-core docs and AST-based symbol inspection. Runs via a
 project-local launcher (`./bin/hoist-core-mcp`) generated by `./gradlew installHoistCoreTools`;
 re-run that task after cloning the repo or bumping `hoistCoreVersion`. Toolbox typically tracks a
-hoist-core SNAPSHOT, so the bundled content stays close to `develop`. Requires Java 17+. The
-same task also writes `./bin/hoist-core-docs` and `./bin/hoist-core-symbols` CLI launchers. See
+hoist-core SNAPSHOT, so the bundled content stays close to `develop`. The same task also writes
+`./bin/hoist-core-docs` and `./bin/hoist-core-symbols` CLI launchers. See
 the `xh:using-hoist-core-reference` skill for the routing table and the full install/upgrade
 procedure.
 
@@ -267,9 +267,11 @@ server only indexes Java source. For navigating into Groovy code, use Grep/Glob
 
 - **Frontend**: TypeScript, React 18, MobX, AG Grid, Highcharts, `@xh/hoist` framework
 - **Backend**: Grails 7 (Groovy/Spring Boot), `hoist-core` framework
-- **JDK**: Java 25 is required for local development and CI. The Gradle toolchain in
-  `build.gradle` pins the language level to 25. (Note that `hoist-core` itself is separately
-  pinned to Java 17 bytecode so its published JAR remains runnable by client apps on JDK 17+.)
+- **JDK**: the JVM version used for local development and CI is set by `majorJavaVersion` in
+  `gradle.properties`; the Gradle toolchain in `build.gradle` reads that value. JDK 25+ is not
+  currently usable — Gradle 8.x caps its compatible JVM at version 24. (Note that `hoist-core`
+  itself is separately pinned to a lower bytecode level so its published JAR remains runnable
+  by older client apps — see `hoist-core` docs for the current minimum.)
 - **Database**: MySQL (or H2 in-memory for quick local dev via `APP_TOOLBOX_USE_H2=true`)
 - **Package Manager**: Yarn 1.22 (frontend), Gradle via wrapper (backend)
 

build.gradle

@@ -44,7 +44,7 @@ springBoot {
 
 java {
     toolchain {
-        languageVersion = JavaLanguageVersion.of(25)
+        languageVersion = JavaLanguageVersion.of(Integer.parseInt(majorJavaVersion))
     }
 }
 

docker/tomcat/Dockerfile

@@ -1,3 +1,3 @@
-FROM xhio/xh-tomcat:next-tc10-jdk25
+FROM xhio/xh-tomcat:next-tc10-jdk21
 COPY setenv.sh bin/
 COPY *.war webapps/ROOT.war

docs/build-and-deploy.md

@@ -15,7 +15,7 @@ that automate that process.
 
 Runs automatically on pushes and pull requests to `develop`. Includes three independent jobs:
 
-- **Build** — checks out the project, sets up JDK 17 and Gradle, and runs `./gradlew build` to
+- **Build** — checks out the project, sets up Java and Gradle, and runs `./gradlew build` to
   validate the Grails server compiles successfully.
 - **Lint** — sets up Node.js (version from `client-app/.nvmrc`), installs JS dependencies via
   `yarn install --frozen-lockfile`, and runs `yarn lint` to validate the client code.

gradle.properties

@@ -3,6 +3,7 @@ xhAppName=Toolbox
 xhAppPackage=io.xh.toolbox
 xhAppVersion=9.0-SNAPSHOT
 
+majorJavaVersion=21
 grailsVersion=7.1.1
 hoistCoreVersion=40.0-SNAPSHOT
 dotEnvGradlePluginVersion=4.0.0