Add gateway implementation planning docs

docs/style-guides/JavaStyleGuide.md

@@ -0,0 +1,65 @@
+# Java Style Guide
+
+This guide defines Java conventions for the MXAccess Gateway Java client
+library, CLI, and tests.
+
+## Baseline
+
+- Target the Java version defined by the client build, with Java 21 preferred.
+- Use Gradle unless the repository standardizes on Maven.
+- Apply a formatter such as Spotless or Google Java Format when configured.
+- Keep generated protobuf code separate from handwritten wrappers.
+
+## Source Documentation
+
+- Maintain the existing documentation style in the file, package, and
+  surrounding component.
+- Write comments that include business-specific or domain-specific context when
+  that context is available from the code, surrounding docs, or naming.
+- Use Javadoc for public APIs when behavior, parity constraints, or security
+  requirements are not obvious from the signature.
+- Avoid comments that restate syntax or control flow.
+
+## Packages
+
+- Use lowercase package names under `com.dohertylan.mxgateway`.
+- Keep client library code separate from CLI code.
+- Keep generated protobuf classes in a generated package.
+- Do not expose implementation-only transport helpers as public API.
+
+## Naming
+
+- Use `PascalCase` for classes, records, interfaces, and enums.
+- Use `camelCase` for methods, fields, parameters, and local variables.
+- Use `UPPER_SNAKE_CASE` for constants.
+- Use MXAccess terms consistently: `serverHandle`, `itemHandle`,
+  `mxStatusProxy`, and `hResult`.
+
+## API Design
+
+- Prefer immutable options objects with builders for public configuration.
+- Implement `AutoCloseable` for clients and sessions that own resources.
+- Provide async methods with `CompletableFuture` where useful, but keep a
+  blocking API for simple CLI workflows.
+- Expose raw generated protobuf messages where parity tests need them.
+
+## Errors
+
+- Use typed exceptions for gateway, authentication, authorization, session,
+  worker, command, and MXAccess failures.
+- Preserve raw command replies in command exceptions when available.
+- Redact API keys, passwords, and secured write values in `toString`, logs, and
+  CLI output.
+
+## Streaming
+
+- Cancel gRPC calls explicitly when callers stop consuming streams.
+- Do not reorder, coalesce, or drop events in client code.
+- Avoid unbounded queues in async stream helpers.
+
+## Tests
+
+- Use JUnit 5.
+- Use in-process gRPC servers for unit tests.
+- Keep live gateway tests behind `MXGATEWAY_INTEGRATION=1` and JUnit
+  assumptions.