From f2118f70288a946d9ecd13b9d7107dbd9861dbf7 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Sun, 26 Apr 2026 21:20:43 -0400
Subject: [PATCH 1/2] Issue #50: document client packaging

---
 clients/dotnet/README.md        |  47 ++++++
 clients/go/README.md            |  42 ++++++
 clients/java/README.md          |  39 +++++
 clients/python/README.md        |  46 ++++++
 clients/rust/README.md          |  29 ++++
 docs/ClientPackaging.md         | 260 ++++++++++++++++++++++++++++++++
 docs/client-libraries-design.md |   1 +
 docs/client-proto-generation.md |  11 ++
 8 files changed, 475 insertions(+)
 create mode 100644 docs/ClientPackaging.md

diff --git a/clients/dotnet/README.md b/clients/dotnet/README.md
index 89150da..f11cc9e 100644
--- a/clients/dotnet/README.md
+++ b/clients/dotnet/README.md
@@ -23,6 +23,29 @@ dotnet build clients/dotnet/MxGateway.Client.sln
 dotnet test clients/dotnet/MxGateway.Client.sln --no-build
 ```
 
+## Packaging
+
+Create local library and CLI artifacts from the repository root:
+
+```powershell
+$dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
+dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
+```
+
+The library package references the shared contracts project at build time. The
+published CLI runs from `artifacts/clients/dotnet/mxgw-dotnet`.
+
+## Regenerating Protobuf Bindings
+
+The .NET client uses the generated C# types from
+`src/MxGateway.Contracts/Generated`. Regenerate those files through the
+contracts project:
+
+```powershell
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
 ## Client Usage
 
 `MxGatewayClient` opens a gRPC channel to the gateway and attaches the API key
@@ -109,3 +132,27 @@ dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint htt
 optionally writes a value when `--type` and `--value` are supplied, reads a
 bounded event stream, and closes the session in a `finally` block. CLI error
 output redacts API keys supplied through `--api-key`.
+
+Use TLS options for a secured gateway:
+
+```powershell
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
+```
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'http://localhost:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'Area001.Pump001.Speed'
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
+## Related Documentation
+
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [.NET Client Detailed Design](../../docs/clients-dotnet-csharp-design.md)
diff --git a/clients/go/README.md b/clients/go/README.md
index 00c1024..cbc2219 100644
--- a/clients/go/README.md
+++ b/clients/go/README.md
@@ -44,6 +44,24 @@ The tests parse the shared JSON fixtures, exercise value and status conversion,
 use `bufconn` for fake gateway auth and streaming behavior, and cover CLI JSON
 redaction.
 
+## Packaging
+
+Build a local CLI executable from `clients/go`:
+
+```powershell
+New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
+go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
+```
+
+Install the CLI into the active `GOBIN` or `GOPATH/bin`:
+
+```powershell
+go install ./cmd/mxgw-go
+```
+
+Other Go modules can consume the library package with the module path
+`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway`.
+
 ## Client API
 
 Use `mxgateway.Dial` with `mxgateway.Options` to configure plaintext or TLS
@@ -81,3 +99,27 @@ go run ./cmd/mxgw-go smoke -item Area001.Tag.Value -plaintext -json
 
 Use `-api-key-env MXGATEWAY_API_KEY` or `-api-key <key>` when authentication is
 enabled. CLI output redacts the key value and never writes the raw secret.
+
+Use TLS options for a secured gateway:
+
+```powershell
+go run ./cmd/mxgw-go smoke -endpoint mxgateway.example.local:5001 -ca-cert C:\certs\mxgateway-ca.pem -server-name-override mxgateway.example.local -api-key-env MXGATEWAY_API_KEY -item Area001.Tag.Value -json
+```
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'Area001.Tag.Value'
+go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
+```
+
+## Related Documentation
+
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [Go Client Detailed Design](../../docs/clients-golang-design.md)
diff --git a/clients/java/README.md b/clients/java/README.md
index 0f8c6c5..222703c 100644
--- a/clients/java/README.md
+++ b/clients/java/README.md
@@ -27,6 +27,15 @@ generated stubs, and generated protobuf messages for parity tests.
 application entry point. The CLI supports version, session, command, event
 streaming, write, and smoke-test commands with deterministic JSON output.
 
+## Regenerating Protobuf Bindings
+
+Run generation from `clients/java` after the shared `.proto` files or Java
+output path changes:
+
+```powershell
+gradle :mxgateway-client:generateProto
+```
+
 ## Client Usage
 
 Create a client with explicit transport and auth options:
@@ -77,6 +86,12 @@ The CLI accepts `--api-key`, `--api-key-env`, `--plaintext`, `--ca-file`,
 `--server-name-override`, `--timeout`, and `--json` on gateway commands. JSON
 output redacts API keys.
 
+Use TLS options for a secured gateway:
+
+```powershell
+gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestObject.TestInt --json"
+```
+
 ## Build And Test
 
 Run the Java checks from `clients/java`:
@@ -89,8 +104,32 @@ The build uses the Java 21 Gradle toolchain, compiles generated protobuf/gRPC
 code, and runs JUnit 5 tests for the client wrapper, shared behavior fixtures,
 in-process gRPC behavior, stream cancellation, and CLI parser/output behavior.
 
+## Packaging
+
+Create local library and CLI artifacts from `clients/java`:
+
+```powershell
+gradle :mxgateway-client:jar :mxgateway-cli:installDist
+```
+
+The library jar is under `mxgateway-client/build/libs`. The installed CLI
+distribution is under `mxgateway-cli/build/install/mxgateway-cli`.
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
+gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+```
+
 ## Related Documentation
 
+- [Client Packaging](../../docs/ClientPackaging.md)
 - [Client Proto Generation](../../docs/client-proto-generation.md)
 - [Java Client Detailed Design](../../docs/clients-java-design.md)
 - [Java Style Guide](../../docs/style-guides/JavaStyleGuide.md)
diff --git a/clients/python/README.md b/clients/python/README.md
index 2169299..10d9035 100644
--- a/clients/python/README.md
+++ b/clients/python/README.md
@@ -47,6 +47,28 @@ The tests import the generated gateway and worker stubs, run fake async gateway
 stubs, verify API key metadata, exercise stream cancellation, load shared value
 and command fixtures, and check deterministic CLI output.
 
+## Packaging
+
+Install the package in editable mode for local development:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Build a wheel from `clients/python`:
+
+```powershell
+python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel"
+```
+
+Install the generated wheel into a target environment:
+
+```powershell
+python -m pip install <wheel-path>
+```
+
+The wheel exposes the `mxgw-py` console script.
+
 ## Library Usage
 
 The library is async-first:
@@ -105,3 +127,27 @@ mxgw-py write --session-id <id> --server-handle 1 --item-handle 2 --type int32 -
 Use `--api-key` or `--api-key-env MXGATEWAY_API_KEY` to attach API key
 metadata. `smoke` opens a session, registers, adds an item, advises, streams a
 bounded event count, and closes the session in a `finally` block.
+
+Use TLS options for a secured gateway:
+
+```powershell
+mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item Object.Attribute --json
+```
+
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'Object.Attribute'
+mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
+## Related Documentation
+
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [Python Client Detailed Design](../../docs/clients-python-design.md)
diff --git a/clients/rust/README.md b/clients/rust/README.md
index 9458619..8316002 100644
--- a/clients/rust/README.md
+++ b/clients/rust/README.md
@@ -38,6 +38,18 @@ cargo clippy --workspace --all-targets -- -D warnings
 The build script uses `protoc` from `PATH` or the Windows path recorded in
 `../../docs/toolchain-links.md`.
 
+## Packaging
+
+Create local release artifacts from `clients/rust`:
+
+```powershell
+cargo build --workspace --release
+cargo install --path crates/mxgw-cli --locked --force
+```
+
+`cargo check --workspace` regenerates the `tonic` and `prost` modules into
+Cargo build output through `build.rs`.
+
 ## CLI
 
 The CLI exposes version, session, command, event stream, write, and smoke
@@ -58,6 +70,10 @@ CLI reads the API key from `--api-key` or from `--api-key-env`, which defaults
 to `MXGATEWAY_API_KEY`. API keys are redacted by the library option and secret
 types.
 
+```powershell
+cargo run -p mxgw-cli -- smoke --endpoint https://mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestChildObject.TestInt --json
+```
+
 ## Library Surface
 
 `ClientOptions` configures endpoint, API key, plaintext or TLS transport,
@@ -83,8 +99,21 @@ preserving the raw message for parity diagnostics. Command replies whose
 protocol status is not `PROTOCOL_STATUS_CODE_OK` become `Error::Command` and
 retain the raw `MxCommandReply`.
 
+## Integration Checks
+
+Run live checks only when a gateway and MXAccess-backed worker are available:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'http://127.0.0.1:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'TestChildObject.TestInt'
+cargo run -p mxgw-cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
 ## Related Documentation
 
+- [Client Packaging](../../docs/ClientPackaging.md)
 - [Client Proto Generation](../../docs/client-proto-generation.md)
 - [Rust Client Detailed Design](../../docs/clients-rust-design.md)
 - [Rust Style Guide](../../docs/style-guides/RustStyleGuide.md)
diff --git a/docs/ClientPackaging.md b/docs/ClientPackaging.md
new file mode 100644
index 0000000..fb7c9dd
--- /dev/null
+++ b/docs/ClientPackaging.md
@@ -0,0 +1,260 @@
+# Client Packaging
+
+This document defines the clean-checkout commands for building, packaging, and
+running the official MXAccess Gateway clients. Use the tool paths and versions
+in [Toolchain Links](./toolchain-links.md) when a command is missing from
+`PATH`.
+
+## Shared Inputs
+
+All clients generate bindings from the shared protobuf files under
+`src/MxGateway.Contracts/Protos`. Regenerate the published client descriptor
+after changing either `.proto` file or `clients/proto/proto-inputs.json`:
+
+```powershell
+scripts/publish-client-proto-inputs.ps1
+scripts/publish-client-proto-inputs.ps1 -Check
+```
+
+Generated protobuf and gRPC files are generator output. Do not edit them by
+hand.
+
+## Environment
+
+The examples use these common variables:
+
+```powershell
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
+```
+
+Use plaintext only for a local gateway. Use TLS when the gateway crosses a
+machine boundary or uses a production certificate.
+
+## .NET
+
+The .NET client uses .NET 10 and references
+`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated C# contract
+types. `clients/dotnet/generated` remains reserved for client-local generator
+output if the client later decouples from the contracts project.
+
+Regenerate the generated C# contract types:
+
+```powershell
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
+Build and test from the repository root:
+
+```powershell
+dotnet build clients/dotnet/MxGateway.Client.sln
+dotnet test clients/dotnet/MxGateway.Client.sln --no-build
+```
+
+Create local package artifacts:
+
+```powershell
+$dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
+dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
+```
+
+Run the CLI from source:
+
+```powershell
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint "http://$env:MXGATEWAY_ENDPOINT" --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+```
+
+## Go
+
+The Go client is the module
+`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go`.
+Generated Go files live under `clients/go/internal/generated`.
+
+Regenerate the Go bindings:
+
+```powershell
+Push-Location clients/go
+./generate-proto.ps1
+Pop-Location
+```
+
+Build and test from `clients/go`:
+
+```powershell
+Push-Location clients/go
+go test ./...
+go build ./...
+go vet ./...
+Pop-Location
+```
+
+Create a local CLI executable:
+
+```powershell
+Push-Location clients/go
+New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
+go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
+Pop-Location
+```
+
+Run the CLI from source:
+
+```powershell
+Push-Location clients/go
+go run ./cmd/mxgw-go version -json
+go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
+go run ./cmd/mxgw-go smoke -endpoint mxgateway.example.local:5001 -ca-cert C:\certs\mxgateway-ca.pem -server-name-override mxgateway.example.local -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
+Pop-Location
+```
+
+## Rust
+
+The Rust workspace builds the `mxgateway-client` library crate and the `mxgw`
+CLI crate. `build.rs` generates `tonic` and `prost` modules into Cargo build
+output on each build that needs updated protobuf output.
+
+Regenerate and compile Rust bindings:
+
+```powershell
+Push-Location clients/rust
+cargo check --workspace
+Pop-Location
+```
+
+Build and test from `clients/rust`:
+
+```powershell
+Push-Location clients/rust
+cargo fmt --all --check
+cargo test --workspace
+cargo check --workspace
+Pop-Location
+```
+
+Create local release artifacts:
+
+```powershell
+Push-Location clients/rust
+cargo build --workspace --release
+cargo install --path crates/mxgw-cli --locked --force
+Pop-Location
+```
+
+Run the CLI from source:
+
+```powershell
+Push-Location clients/rust
+cargo run -p mxgw-cli -- version --json
+cargo run -p mxgw-cli -- smoke --endpoint "http://127.0.0.1:5000" --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+cargo run -p mxgw-cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+Pop-Location
+```
+
+## Python
+
+The Python package is `mxaccess-gateway-client`. Generated modules live under
+`clients/python/src/mxgateway/generated`.
+
+Regenerate the Python bindings:
+
+```powershell
+Push-Location clients/python
+./generate-proto.ps1
+Pop-Location
+```
+
+Install, test, and build a wheel from `clients/python`:
+
+```powershell
+Push-Location clients/python
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel"
+Pop-Location
+```
+
+Run the CLI from the editable install or with `python -m`:
+
+```powershell
+Push-Location clients/python
+mxgw-py version --json
+mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
+python -m mxgateway_cli version --json
+Pop-Location
+```
+
+## Java
+
+The Java workspace uses Gradle, Java 21, `mxgateway-client`, and
+`mxgateway-cli`. The Gradle protobuf plugin writes generated Java protobuf and
+gRPC sources under `clients/java/src/main/generated`.
+
+Regenerate Java bindings:
+
+```powershell
+Push-Location clients/java
+gradle :mxgateway-client:generateProto
+Pop-Location
+```
+
+Build and test from `clients/java`:
+
+```powershell
+Push-Location clients/java
+gradle test
+Pop-Location
+```
+
+Create local library and CLI artifacts:
+
+```powershell
+Push-Location clients/java
+gradle :mxgateway-client:jar :mxgateway-cli:installDist
+Pop-Location
+```
+
+Run the CLI through Gradle:
+
+```powershell
+Push-Location clients/java
+gradle :mxgateway-cli:run --args="version --json"
+gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
+Pop-Location
+```
+
+## Integration Tests
+
+Client integration checks are opt-in because they need a live gateway and a
+gateway host that can create MXAccess worker sessions. Set the common
+environment before running a client smoke:
+
+```powershell
+$env:MXGATEWAY_INTEGRATION = '1'
+$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
+$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
+$env:MXGATEWAY_TEST_CONTEXT = ''
+$env:MXGATEWAY_TEST_WRITE_VALUE = '123'
+```
+
+Run the bounded `smoke` command for each client against the same item. The
+smoke commands open a session, register a client name, add one item, advise it,
+and close the session. The .NET and Python smoke commands also read a bounded
+event stream; the Go, Rust, and Java smoke commands exercise the command path
+and can be paired with their `stream-events` commands after a session is open.
+
+Client-side cancellation or timeout stops waiting for the gateway response. It
+does not abort an MXAccess COM call that is already executing on the worker STA.
+
+## Related Documentation
+
+- [Client Proto Generation](./client-proto-generation.md)
+- [Client Libraries Detailed Design](./client-libraries-design.md)
+- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
+- [Toolchain Links](./toolchain-links.md)
diff --git a/docs/client-libraries-design.md b/docs/client-libraries-design.md
index f2e2054..9750551 100644
--- a/docs/client-libraries-design.md
+++ b/docs/client-libraries-design.md
@@ -30,6 +30,7 @@ Shared generation inputs:
 
 - `docs/client-proto-generation.md`
 - `docs/ClientBehaviorFixtures.md`
+- `docs/ClientPackaging.md`
 - `clients/proto/proto-inputs.json`
 
 Language style guides:
diff --git a/docs/client-proto-generation.md b/docs/client-proto-generation.md
index bcd517f..74d14e9 100644
--- a/docs/client-proto-generation.md
+++ b/docs/client-proto-generation.md
@@ -86,6 +86,16 @@ All generators use `src/MxGateway.Contracts/Protos` as the protobuf import
 root. The checked-in descriptor is available when a language build prefers a
 descriptor input, but the `.proto` files remain canonical.
 
+Use these commands to regenerate language-specific client bindings:
+
+| Client | Command |
+|--------|---------|
+| .NET | `dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj` |
+| Go | `Push-Location clients/go; ./generate-proto.ps1; Pop-Location` |
+| Rust | `Push-Location clients/rust; cargo check --workspace; Pop-Location` |
+| Python | `Push-Location clients/python; ./generate-proto.ps1; Pop-Location` |
+| Java | `Push-Location clients/java; gradle :mxgateway-client:generateProto; Pop-Location` |
+
 .NET generation currently runs through the contracts project:
 
 ```powershell
@@ -186,6 +196,7 @@ scripts/validate-client-behavior-fixtures.ps1
 
 - [Protobuf Contracts](./Contracts.md)
 - [Client Libraries Detailed Design](./client-libraries-design.md)
+- [Client Packaging](./ClientPackaging.md)
 - [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
 - [Client Libraries Implementation Plan](./implementation-plan-clients.md)
 - [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)

From 4ea2c4fd8618adc45258c84a32203d4aa916155b Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Sun, 26 Apr 2026 21:26:28 -0400
Subject: [PATCH 2/2] Issue #50: clarify packaging API key placeholders

---
 clients/dotnet/README.md | 2 +-
 clients/go/README.md     | 2 +-
 clients/java/README.md   | 2 +-
 clients/python/README.md | 4 ++--
 clients/rust/README.md   | 2 +-
 docs/ClientPackaging.md  | 4 ++--
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/clients/dotnet/README.md b/clients/dotnet/README.md
index f11cc9e..223746b 100644
--- a/clients/dotnet/README.md
+++ b/clients/dotnet/README.md
@@ -146,7 +146,7 @@ Run live checks only when a gateway and MXAccess-backed worker are available:
 ```powershell
 $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'http://localhost:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'Area001.Pump001.Speed'
 dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
 ```
diff --git a/clients/go/README.md b/clients/go/README.md
index cbc2219..4f73d97 100644
--- a/clients/go/README.md
+++ b/clients/go/README.md
@@ -113,7 +113,7 @@ Run live checks only when a gateway and MXAccess-backed worker are available:
 ```powershell
 $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'Area001.Tag.Value'
 go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
 ```
diff --git a/clients/java/README.md b/clients/java/README.md
index 222703c..5bce284 100644
--- a/clients/java/README.md
+++ b/clients/java/README.md
@@ -122,7 +122,7 @@ Run live checks only when a gateway and MXAccess-backed worker are available:
 ```powershell
 $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
 gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
 ```
diff --git a/clients/python/README.md b/clients/python/README.md
index 10d9035..677e2ec 100644
--- a/clients/python/README.md
+++ b/clients/python/README.md
@@ -78,7 +78,7 @@ from mxgateway import GatewayClient
 
 async with await GatewayClient.connect(
     endpoint="localhost:5000",
-    api_key="mxgw_example",
+    api_key="<gateway-api-key>",
     plaintext=True,
 ) as client:
     session = await client.open_session(client_session_name="python-client")
@@ -141,7 +141,7 @@ Run live checks only when a gateway and MXAccess-backed worker are available:
 ```powershell
 $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'Object.Attribute'
 mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
 ```
diff --git a/clients/rust/README.md b/clients/rust/README.md
index 8316002..47eb700 100644
--- a/clients/rust/README.md
+++ b/clients/rust/README.md
@@ -106,7 +106,7 @@ Run live checks only when a gateway and MXAccess-backed worker are available:
 ```powershell
 $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'http://127.0.0.1:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'TestChildObject.TestInt'
 cargo run -p mxgw-cli -- smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
 ```
diff --git a/docs/ClientPackaging.md b/docs/ClientPackaging.md
index fb7c9dd..bf8aec6 100644
--- a/docs/ClientPackaging.md
+++ b/docs/ClientPackaging.md
@@ -25,7 +25,7 @@ The examples use these common variables:
 
 ```powershell
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
 ```
 
@@ -237,7 +237,7 @@ environment before running a client smoke:
 ```powershell
 $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
-$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
+$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
 $env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
 $env:MXGATEWAY_TEST_CONTEXT = ''
 $env:MXGATEWAY_TEST_WRITE_VALUE = '123'