diff --git a/CLAUDE.md b/CLAUDE.md
index 8bae914..156f513 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,6 +21,9 @@ The worker must do all MXAccess COM calls on its dedicated STA thread, and the S
 # Full solution build (gateway, worker, contracts, tests)
 dotnet build src/ZB.MOM.WW.MxGateway.slnx
 
+# Non-Windows hosts (e.g. the macOS working tree): excludes the x86 Worker + Worker.Tests
+dotnet build src/ZB.MOM.WW.MxGateway.NonWindows.slnx
+
 # Worker must be built x86 — the gateway looks for ZB.MOM.WW.MxGateway.Worker.exe under bin\x86
 dotnet build src/ZB.MOM.WW.MxGateway.Worker/ZB.MOM.WW.MxGateway.Worker.csproj -p:Platform=x86
 
@@ -57,7 +60,7 @@ Each language client is in `clients/<lang>/` with its own README. They all consu
 - `clients/dotnet`: `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx`
 - `clients/python`: `python -m pip install -e ".[dev]"; python -m pytest`
 - `clients/rust`: `cargo test --workspace; cargo clippy --workspace --all-targets -- -D warnings`
-- `clients/java`: `gradle test` (Java 21)
+- `clients/java`: `gradle test` (Java 17 — retargeted from 21 for Ignition 8.3)
 - Go client lives alongside as `mxgw-go` in the cross-language matrix
 
 End-to-end matrix runner (needs running gateway + worker + valid API key):
@@ -122,6 +125,6 @@ Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` b
 
 ## Process / Platform Notes
 
-- Working tree is on Windows (`C:\Users\dohertj2\Desktop\mxaccessgw`). PowerShell is the native shell for tooling commands; bash is fine for git/grep/find.
-- The worker reference to `ArchestrA.MXAccess.dll` uses an absolute `HintPath` to `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`. The worker only builds where MXAccess is installed (this dev box).
-- The repo is not a git repository at the top level — there's no `.git` directory in the working tree.
+- The working tree is cross-platform. On the macOS dev box (`/Users/dohertj2/Desktop/MxAccessGateway`, zsh) build the `NonWindows.slnx`; the x86 Worker and the full `slnx` only build on a Windows host with MXAccess installed. PowerShell is the native shell on Windows; bash/zsh is fine for git/grep/find.
+- The worker reference to `ArchestrA.MXAccess.dll` uses an absolute `HintPath` to `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`. The worker only builds where MXAccess is installed (the Windows dev box).
+- The working tree is a git repository. Main branch is `main`; feature work happens on branches (e.g. `feat/*`).
diff --git a/docs/ToolchainLinks.md b/docs/ToolchainLinks.md
index 54f17ae..e6fbec5 100644
--- a/docs/ToolchainLinks.md
+++ b/docs/ToolchainLinks.md
@@ -123,6 +123,11 @@ typer==0.25.0
 | Gradle | 9.4.1 | `C:\Tools\gradle-9.4.1\bin\gradle.bat` |
 | Maven | 3.9.15 | `C:\Tools\apache-maven-3.9.15\bin\mvn.cmd` |
 
+The Java client was retargeted 21 -> 17 for Ignition 8.3 (`clients/java/build.gradle`
+declares a `JavaLanguageVersion.of(17)` toolchain). Gradle resolves toolchains by
+version, so a JDK 17 must be available on the build host even though the runtime
+above is Temurin 21 (a 17-targeted build still runs on 21+).
+
 Environment:
 
 ```text