Issue #47: scaffold Java Gradle build

docs/client-proto-generation.md

@@ -137,9 +137,17 @@ The Python scaffold provides a repo-local generation script:
 clients/python/generate-proto.ps1
 ```
 
-Java clients should use the Gradle protobuf plugin and write generated sources
-under `clients/java/src/main/generated`. The Java client scaffold owns the
-Gradle plugin versions and source-set wiring.
+Java clients use the Gradle protobuf plugin from `clients/java`. The
+`mxgateway-client` project reads the shared `.proto` files and writes generated
+Java protobuf and gRPC sources under `clients/java/src/main/generated`, matching
+the manifest output path. Handwritten client and CLI code stays in the
+`mxgateway-client` and `mxgateway-cli` project source trees.
+
+Run the Java workspace checks from `clients/java`:
+
+```powershell
+gradle test
+```
 
 ## Golden Fixtures
 

docs/clients-java-design.md

@@ -17,6 +17,7 @@ Recommended Gradle multi-project layout:
 clients/java/
   settings.gradle
   build.gradle
+  src/main/generated/
   mxgateway-client/
     build.gradle
     src/main/java/com/dohertylan/mxgateway/client/
@@ -31,6 +32,7 @@ Alternative Maven layout is acceptable if the repo standardizes on Maven.
 Target Java:
 
 - Java 21 recommended.
+- The Gradle scaffold uses the Java 21 toolchain for compilation and tests.
 
 Expected dependencies:
 
@@ -189,3 +191,16 @@ Publish library and CLI separately:
 
 Generated protobuf code should be produced during the build from shared proto
 files and should not be hand-edited.
+
+## Current Build
+
+Run the Java scaffold checks from `clients/java`:
+
+```powershell
+gradle test
+```
+
+The `mxgateway-client` project generates the gateway and worker protobuf/gRPC
+bindings into `src/main/generated`, compiles the generated contracts, and runs
+JUnit 5 tests. The `mxgateway-cli` project builds a Picocli-based `mxgw-java`
+entry point for later command implementation.