code-review: regen README, all 21 open findings resolved

Closes the 2026-05-24 resolution sweep at HEAD `83eba4b`. All 21 open
findings from the d692232 re-review are now Resolved:

  Server          327e9c5  Server-031, -032, -038, -039, -040, -041, -042, -043
  Contracts       bd1d1f1  Contracts-016, -017
  Tests           d48099f  Tests-025, -026
  IntegrationTests 865c22a IntegrationTests-022, -023, -024
  Client.Java     10bd0c0  Client.Java-027, -028, -029, -030, -031
  Client.Rust     83eba4b  Client.Rust-021

Also fixes stale "Open findings" header counts in Client.Java and
IntegrationTests findings.md that survived the resolve passes
(the agents updated each finding's Status but missed the header
sum). `regen-readme.py --check` is now green.

Module status: 11 / 11 reviewed, 0 / 276 total open.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -1,481 +0,0 @@
-# MXAccess Gateway Agent Guide
-
-Repository: https://gitea.dohertylan.com/dohertj2/mxaccessgw
-
-This project builds a gateway that gives modern clients full MXAccess parity
-without requiring those clients to load MXAccess COM, run as x86, or own an STA
-message pump. Treat the installed MXAccess COM component as the compatibility
-baseline.
-
-Toolchain paths, versions, and external analysis locations are recorded in
-`docs/toolchain-links.md`. Use that file before searching for compilers,
-runtimes, protobuf tools, MXAccess notes, or Galaxy Repository SQL notes.
-
-Implementation planning is recorded in `docs/implementation-plan-index.md`.
-Follow the order there unless the user explicitly reprioritizes: gateway first,
-MXAccess worker instance second, clients third.
-
-## Core Contract
-
-Preserve MXAccess behavior first:
-
-- public MXAccess command semantics,
-- native MXAccess event families,
-- STA/message-pump delivery behavior,
-- installed-provider quirks,
-- HRESULT/status/value marshaling,
-- per-client isolation.
-
-Do not simplify, normalize, or "fix" MXAccess behavior unless an explicit
-non-parity mode is being implemented and tested. `MxAsbClient` and managed NMX
-are future acceleration paths only; they do not define the parity contract.
-
-## Architecture
-
-The intended split is:
-
-```text
-client
-  -> gRPC over TCP
-    -> .NET 10 x64 gateway
-      -> session manager
-        -> per-session .NET Framework 4.8 x86 worker process
-          -> dedicated STA thread
-            -> MXAccess COM instance
-            -> Windows/COM message pump
-            -> command queue
-            -> event sink
-```
-
-The gateway must never instantiate or call MXAccess directly. All MXAccess COM
-interaction belongs in the worker process on its dedicated STA thread.
-
-The worker must not host public gRPC. Gateway-to-worker communication should use
-a small local IPC protocol, with named pipes and protobuf-framed messages as the
-default design.
-
-## Runtime Targets
-
-- Gateway: .NET 10, C#, x64 preferred, ASP.NET Core gRPC.
-- Worker: .NET Framework 4.8, C#, x86 by default.
-- Worker IPC: one bidirectional named pipe per worker.
-- Worker process model: one external client session maps to one worker by
-  default.
-
-## Style Guides
-
-Follow the project documentation guide and the language guide for every changed
-area:
-
-| Area | Style guide |
-|------|-------------|
-| Documentation | `StyleGuide.md` |
-| Gateway, worker, .NET client, and C# tests | `docs/style-guides/CSharpStyleGuide.md` |
-| Public gRPC and worker IPC contracts | `docs/style-guides/ProtobufStyleGuide.md` |
-| Go client | `docs/style-guides/GoStyleGuide.md` |
-| Rust client | `docs/style-guides/RustStyleGuide.md` |
-| Python client | `docs/style-guides/PythonStyleGuide.md` |
-| Java client | `docs/style-guides/JavaStyleGuide.md` |
-
-When a change crosses languages, apply every affected style guide. Generated
-code follows its generator output; do not hand-edit it to match handwritten
-style.
-
-## Expected Layout
-
-Prefer this structure unless there is a strong reason to adjust it:
-
-```text
-src/MxGateway.Contracts/
-  Protos/
-    mxaccess_gateway.proto
-    mxaccess_worker.proto
-  Generated/
-
-src/MxGateway.Server/
-  Program.cs
-  Sessions/
-  Workers/
-  Grpc/
-  Dashboard/
-  Metrics/
-
-src/MxGateway.Worker/
-  Program.cs
-  Ipc/
-  Sta/
-  MxAccess/
-  Conversion/
-
-src/MxGateway.Tests/
-  contract tests
-  gateway session tests
-  fake worker tests
-
-src/MxGateway.Worker.Tests/
-  value/status conversion tests
-  STA queue tests
-
-src/MxGateway.IntegrationTests/
-  optional live MXAccess tests
-
-clients/dotnet/
-  .NET 10 C# client library, test CLI, and tests
-
-clients/go/
-  Go client module, test CLI, and tests
-
-clients/rust/
-  Rust client crate, test CLI, and tests
-
-clients/python/
-  Python client package, test CLI, and tests
-
-clients/java/
-  Java client library, test CLI, and tests
-```
-
-The contracts project may multi-target, or the `.proto` files may be shared as
-source inputs to both gateway and worker builds.
-
-## Public API Shape
-
-The external API should be session-oriented. Initial rollout should prefer
-unary `OpenSession`, `CloseSession`, and `Invoke`, plus server-streaming
-`StreamEvents`. Add a bidirectional `Session` stream after the command and event
-model is stable.
-
-Do not compress MXAccess into generic verbs too early. Use a command enum with
-method-specific payloads so parity can be tested method by method.
-
-Core MXAccess commands to represent:
-
-- `Register`
-- `Unregister`
-- `AddItem`
-- `AddItem2`
-- `RemoveItem`
-- `Advise`
-- `UnAdvise`
-- `AdviseSupervisory`
-- `AddBufferedItem`
-- `SetBufferedUpdateInterval`
-- `Suspend`
-- `Activate`
-- `Write`
-- `Write2`
-- `WriteSecured`
-- `WriteSecured2`
-- `AuthenticateUser`
-- `ArchestrAUserToId`
-
-Diagnostics may include `Ping`, `GetSessionState`, `GetWorkerInfo`,
-`DrainEvents`, and `ShutdownWorker`.
-
-## Event Requirements
-
-Represent every public MXAccess event family:
-
-- `OnDataChange`
-- `OnWriteComplete`
-- `OperationComplete`
-- `OnBufferedDataChange`
-
-Preserve per-worker event order. The gateway must not reorder events emitted by
-the same MXAccess instance.
-
-Event DTOs should carry event family, session id, server handle, item handle,
-value, quality, timestamp, `MXSTATUS_PROXY[]` equivalent, raw HRESULT/status
-fields when available, event sequence, worker timestamp, and gateway receive
-timestamp.
-
-## Value And Status Rules
-
-Use a protobuf value union that can represent COM `VARIANT` values and arrays.
-When a value cannot be losslessly converted, preserve both the best typed
-projection and enough raw diagnostic metadata to reproduce the case.
-
-Represent `MXSTATUS_PROXY` explicitly. Do not collapse status arrays into a
-single success flag.
-
-Command replies should include protocol status, COM HRESULT if available,
-MXAccess return values, method-specific out parameters, and status arrays where
-the MXAccess method emits them.
-
-## Galaxy Repository SQL Discovery
-
-Galaxy tags, hierarchy, and attribute details can be queried from the AVEVA /
-Wonderware System Platform Galaxy Repository SQL Server database. Use this as a
-discovery and metadata path only; runtime MXAccess parity still belongs to the
-MXAccess-backed worker unless an explicit non-parity backend is being designed.
-
-Full notes, schema details, screenshots, and query examples are in:
-
-```text
-C:\Users\dohertj2\Desktop\lmxopcua\gr
-```
-
-Important files in that notes directory:
-
-- `connectioninfo.md` - SQL Server connection details and `sqlcmd` usage.
-- `layout.md` - hierarchy vs `tag_name` relationship.
-- `build_layout_plan.md` - extraction plan for hierarchy and attributes.
-- `schema.md` and `ddl/` - Galaxy Repository schema reference.
-- `queries/hierarchy.sql` - deployed object hierarchy.
-- `queries/attributes.sql` - user-defined dynamic attributes.
-- `queries/attributes_extended.sql` - system plus user-defined attributes.
-- `queries/change_detection.sql` - deployment-change polling via
-  `galaxy.time_of_last_deploy`.
-
-Current documented connection is SQL Server `localhost`, database `ZB`, Windows
-Auth. Example:
-
-```powershell
-sqlcmd -S localhost -d ZB -E -Q "SELECT time_of_last_deploy FROM galaxy;"
-```
-
-Key tables from the notes are `gobject`, `template_definition`,
-`dynamic_attribute`, `attribute_definition`, `primitive_instance`, and
-`galaxy`. The hierarchy uses contained names for human-readable browsing, while
-runtime tag references use globally unique `tag_name` values such as
-`<tag_name>.<AttributeName>`.
-
-## MXAccess Analysis Source
-
-Use the local MXAccess analysis project when answering questions about installed
-MXAccess classes, interfaces, fields, events, HRESULT/status behavior, value
-projection, captures, and parity gaps:
-
-```text
-C:\Users\dohertj2\Desktop\mxaccess
-```
-
-Primary files:
-
-- `README.md` - overview of available analysis and capture artifacts.
-- `docs/MXAccess-Public-API.md` - COM class, ProgID, CLSID, method list,
-  event signatures, `MxDataType`, `MxStatus`, and `MXSTATUS_PROXY`.
-- `docs/MXAccess-Reverse-Engineering.md` - installed runtime path and x86 COM
-  constraints.
-- `docs/Current-Sprint-State.md` and `docs/DotNet10-Native-Library-Plan.md` -
-  current parity gaps and managed native-client research status.
-- `src/MxTraceHarness/` - x86 MXAccess harness examples using the real COM
-  interop assembly.
-- `captures/` and `analysis/` - observed native behavior and generated
-  reverse-engineering artifacts.
-
-Concrete MXAccess COM target from the analysis:
-
-- class: `ArchestrA.MxAccess.LMXProxyServerClass`
-- CLSID: `{C30B52F5-2CB5-4760-AF0A-3A344A7EB5DC}`
-- ProgID: `LMXProxy.LMXProxyServer.1`
-- version-independent ProgID: `LMXProxy.LMXProxyServer`
-- registered server: `C:\Program Files (x86)\ArchestrA\Framework\Bin\LmxProxy.dll`
-- interop assembly:
-  `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`
-- threading model: `Apartment`
-
-## Worker Rules
-
-Each worker owns:
-
-- one process,
-- one MXAccess session,
-- one dedicated STA thread,
-- one MXAccess COM object,
-- one inbound command queue,
-- one outbound event queue.
-
-All MXAccess operations must run on the STA. A plain blocking queue is not
-enough for the STA; the STA loop must pump Windows/COM messages and service
-queued commands.
-
-Do not block the STA on pipe writes, gRPC calls, or slow consumers. Event
-handlers should convert event args, enqueue outbound events, and return to
-pumping messages.
-
-On graceful shutdown, reject new commands, optionally clean up active MXAccess
-handles, detach events, release the COM object, uninitialize COM, and exit. If
-graceful shutdown exceeds the configured timeout, the gateway may kill the
-worker.
-
-## IPC Rules
-
-Default pipe name shape:
-
-```text
-mxaccess-gateway-{gatewayProcessId}-{sessionId}
-```
-
-Frame messages as:
-
-```text
-uint32 little-endian payload_length
-payload_length bytes protobuf WorkerEnvelope
-```
-
-Every envelope should include protocol version, session id, monotonic sender
-sequence, correlation id, and a typed body. Protocol version mismatch should
-fail session creation.
-
-Pipe security should be local-machine only, with ACLs restricted to the gateway
-identity and launched worker identity. Prefer a per-session nonce handshake.
-
-## Gateway Rules
-
-The gateway is responsible for:
-
-- public TCP/gRPC API,
-- Blazor Server dashboard using Bootstrap CSS/JS only,
-- authn/authz when needed,
-- session creation and teardown,
-- worker launch and lifecycle management,
-- command routing,
-- event streaming,
-- leases, heartbeats, timeouts, and quotas,
-- worker kill/restart policy,
-- metrics and structured logs.
-
-The gRPC layer should stay thin: validate request, find session, call the
-session worker client, map worker replies to public replies, and stream events.
-Keep MXAccess-specific translation logic testable outside the gRPC handlers.
-
-Dashboard code should also stay thin and read-only for v1. Use a snapshot
-service over session/worker/metrics state; do not let Razor components mutate
-gateway sessions or workers directly. Do not use MudBlazor or other Blazor UI
-component libraries.
-
-Gateway restart should not try to reattach old workers in the first version.
-Terminate orphaned workers on startup if that behavior is implemented.
-
-## Command, Timeout, And Cancellation Semantics
-
-Command lifecycle:
-
-```text
-client gRPC command
-gateway validates session and payload
-gateway assigns correlation id
-gateway writes WorkerCommand to pipe
-worker queues command to STA
-STA executes MXAccess method
-worker captures return/out/status/HRESULT
-worker sends WorkerCommandReply
-gateway completes gRPC response
-```
-
-Canceling a gRPC call should stop waiting in the gateway, but it cannot safely
-abort an in-flight COM call on the STA. Hard cancellation means killing the
-worker process.
-
-If a command wedges the STA beyond a configured grace period, the gateway should
-kill the worker and fail the session.
-
-## Backpressure Policy
-
-Worker outbound events must use a bounded queue. For parity testing, prefer
-fail-fast behavior over silent drops. Production coalescing or drop policies
-must be explicit and observable.
-
-The gateway should preserve per-session event order, apply backpressure from
-slow gRPC streams, and disconnect or coalesce only according to an explicit
-policy.
-
-## Security And Logging
-
-Use TLS for remote gRPC when crossing machine boundaries. Authentication may be
-Windows auth, mTLS, or a deployment-specific token.
-
-Commands that write, authenticate users, or alter runtime state need explicit
-authorization design.
-
-Never log passwords or raw credential values for `AuthenticateUser`,
-`WriteSecured`, or related secured operations. Do not log full values by
-default; make value logging opt-in and redacted.
-
-## Testing Expectations
-
-Use focused tests for:
-
-- contract/protobuf compatibility,
-- gateway session state and worker lifecycle,
-- gateway behavior with a fake worker,
-- worker value/status conversion,
-- STA queue and message-pump behavior.
-
-Live MXAccess integration tests are optional but should be isolated because they
-depend on installed COM components and provider behavior.
-
-Parity tests should compare direct MXAccess behavior against the gateway:
-
-- return values,
-- HRESULTs and exceptions,
-- event sequence,
-- value projection,
-- quality/status arrays,
-- invalid handle behavior,
-- cross-server handle behavior,
-- cleanup behavior.
-
-Known important parity areas:
-
-- `WriteSecured` may fail before a value-bearing NMX body is emitted.
-- `WriteSecured2` can succeed in observed native paths.
-- `OperationComplete` is distinct from write completion.
-- `OnBufferedDataChange` has a distinct public event shape.
-- Invalid handles and cross-server handles have specific exception/status
-  behavior.
-- STA message pumping is required for event delivery.
-
-## Source Update Workflow
-
-When source code changes, build the affected component before handing work
-back. If the change crosses component boundaries, build each affected component
-instead of relying on a single top-level build.
-
-Use the native build and test command for each changed area:
-
-| Changed area | Required verification |
-|--------------|-----------------------|
-| Contracts or `.proto` files | regenerate generated code, then build gateway, worker, and every generated client touched by the contract |
-| Gateway server, sessions, workers, gRPC, dashboard, or metrics | build the .NET 10 gateway project and run affected gateway or fake-worker tests |
-| Worker IPC, STA, MXAccess, or conversion code | build the .NET Framework 4.8 x86 worker project and run affected worker tests |
-| Shared test infrastructure | run every test suite that consumes the changed helpers |
-| .NET client | build the .NET client library, CLI, and tests |
-| Go client | run Go formatting, build, and tests for the Go module |
-| Rust client | run Rust formatting, build or check, and tests for the Rust crate |
-| Python client | run Python formatting or linting if configured, package/build checks, and tests |
-| Java client | build the Java client library, CLI, and tests |
-| Integration tests | run them only when the required MXAccess COM component, provider state, and external services are available; otherwise document why they were skipped |
-
-Update affected documentation in the same change as the source update. This
-includes `gateway.md`, component design docs under `docs/`, client docs, API
-contract notes, test instructions, and operational guidance. Documentation must
-follow `StyleGuide.md`: write technical present-tense prose, explain the reason
-for non-obvious choices, use exact code names, specify languages on code
-blocks, use relative links for internal docs, and avoid stale temporary notes.
-Source code and contract changes must also follow the relevant language guide
-from the Style Guides section.
-
-Do not leave documentation describing old behavior after changing public APIs,
-contracts, configuration, build steps, security behavior, event shapes, value
-conversion, status mapping, lifecycle rules, or client semantics.
-
-## Implementation Priority
-
-Build the smallest end-to-end slice first:
-
-1. .NET 10 gateway starts.
-2. Client calls `OpenSession`.
-3. Gateway launches .NET Framework 4.8 x86 worker.
-4. Worker creates STA and MXAccess COM object.
-5. Client calls `Register`.
-6. Client calls `AddItem`.
-7. Client calls `Advise`.
-8. Worker forwards one `OnDataChange` event to the gateway.
-9. Gateway streams the event to the client.
-10. Client calls `CloseSession`.
-11. Gateway shuts down the worker.
-
-That slice proves the high-risk requirements: process isolation, STA ownership,
-message pumping, command routing, and event streaming.

CLAUDE.md

@@ -0,0 +1,125 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`mxaccessgw` is the MXAccess Gateway: a gRPC service that gives modern (.NET, Go, Rust, Python, Java) clients full MXAccess parity without forcing them to load 32-bit MXAccess COM, run x86, or own an STA message pump.
+
+The architecture is a two-process design — read `gateway.md` before making structural changes:
+
+- **Gateway** (`src/MxGateway.Server`, .NET 10, x64): ASP.NET Core gRPC server. Owns the public API, sessions, auth, the Blazor dashboard, and the Galaxy Repository SQL browse RPCs. **Never instantiates MXAccess COM directly.**
+- **Worker** (`src/MxGateway.Worker`, .NET Framework 4.8, **x86**): one process per session. Owns one MXAccess COM instance on a dedicated STA, pumps Windows messages, and converts COM events to protobuf.
+- **IPC**: gateway↔worker uses one bidirectional named pipe per worker (`mxaccess-gateway-{gatewayPid}-{sessionId}`) with length-prefixed `WorkerEnvelope` protobuf frames. Gateway hosts the pipe server and launches the worker. **gRPC is not used inside the worker** — .NET Framework 4.8 doesn't have a first-class gRPC stack.
+- **Contracts** (`src/MxGateway.Contracts`): multi-targets `net10.0;net48` and owns the `.proto` files (`mxaccess_gateway.proto`, `mxaccess_worker.proto`, `galaxy_repository.proto`). All other projects consume the generated types from here. Do not hand-edit anything under `Generated/`.
+
+The worker must do all MXAccess COM calls on its dedicated STA thread, and the STA loop must pump Windows messages (`MsgWaitForMultipleObjectsEx` + `PeekMessage`/`DispatchMessage`) so MXAccess events deliver. A plain blocking queue on an STA is not enough.
+
+## Build, Test, Run
+
+```powershell
+# Full solution build (gateway, worker, contracts, tests)
+dotnet build src/MxGateway.sln
+
+# Worker must be built x86 — the gateway looks for MxGateway.Worker.exe under bin\x86
+dotnet build src/MxGateway.Worker/MxGateway.Worker.csproj -p:Platform=x86
+
+# Gateway tests (no MXAccess required — uses FakeWorkerHarness)
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj
+dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform=x86
+
+# Run gateway locally (defaults bound under MxGateway:* in src/MxGateway.Server/appsettings.json)
+dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj
+
+# API-key admin CLI (same exe, "apikey" subcommand)
+dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session,invoke,event,metadata,admin
+```
+
+Single test by name (xUnit `--filter`):
+
+```powershell
+dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter FullyQualifiedName~GatewayEndToEndFakeWorkerSmokeTests
+```
+
+Live MXAccess integration tests are **opt-in** because they need installed MXAccess COM and live provider state:
+
+```powershell
+$env:MXGATEWAY_RUN_LIVE_MXACCESS_TESTS = "1"
+dotnet test src/MxGateway.IntegrationTests/MxGateway.IntegrationTests.csproj --filter FullyQualifiedName~WorkerLiveMxAccessSmokeTests
+```
+
+Live LDAP tests use `MXGATEWAY_RUN_LIVE_LDAP_TESTS=1`. See `docs/GatewayTesting.md` for the full opt-in matrix and `LiveMxAccessFactAttribute` / `LiveLdapFactAttribute` for the gating logic.
+
+## Clients
+
+Each language client is in `clients/<lang>/` with its own README. They all consume the shared `.proto` files in `src/MxGateway.Contracts/Protos`:
+
+- `clients/dotnet`: `dotnet build clients/dotnet/MxGateway.Client.sln`
+- `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)
+- Go client lives alongside as `mxgw-go` in the cross-language matrix
+
+End-to-end matrix runner (needs running gateway + worker + valid API key):
+
+```powershell
+$env:MXGATEWAY_API_KEY = "<api-key>"
+powershell -ExecutionPolicy Bypass -File scripts/run-client-e2e-tests.ps1
+```
+
+## Repository-Specific Conventions
+
+- **Build properties** (`src/Directory.Build.props`) enforce `Nullable=enable`, `TreatWarningsAsErrors=true`, latest analyzers, and `EnforceCodeStyleInBuild=true`. New warnings break the build — fix them, don't suppress unless the suppression has a narrow reason.
+- **Style guides** in `docs/style-guides/` are authoritative. Follow `CSharpStyleGuide.md` for gateway/worker/.NET-client code: file-scoped namespaces, `sealed` by default, `Async` suffix on Task-returning methods, MXAccess-aligned names (`MxStatusProxy`, `ServerHandle`, `ItemHandle`, `HResult`).
+- **MXAccess parity is the contract.** Don't "fix" surprising MXAccess behavior (e.g., `WriteSecured` failing before a value-bearing NMX body, distinct `OperationComplete` semantics, invalid-handle exceptions) unless the client explicitly opts into a non-parity mode. The installed MXAccess COM component is the baseline.
+- **Don't synthesize events.** The gateway forwards only events the worker emits; it never invents `OperationComplete` from write completion or command replies.
+- **One worker per session, one event subscriber per session** (v1). Multi-subscriber fan-out and reconnectable sessions are explicitly out of scope — see `docs/DesignDecisions.md`.
+- **Gateway restart does not reattach orphan workers.** The first version terminates orphaned workers on startup; do not design code paths that assume reattachment.
+- **No Blazor UI component libraries.** Dashboard uses local Bootstrap CSS/JS only — do not introduce MudBlazor, Radzen, FluentUI, etc.
+- **Don't log secrets or full tag values by default.** API keys, passwords, `WriteSecured` payloads, and `AuthenticateUser` credentials must never reach logs. Value logging is opt-in and redacted.
+- **Generated code** under `src/MxGateway.Contracts/Generated/`, `clients/*/generated*/`, `clients/python/src/mxgateway/generated/`, etc., is build output. Don't hand-edit. To regenerate, build the contracts project (`dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj`) or run the per-client generation step in that client's README.
+- **Documentation style** (`StyleGuide.md`): PascalCase filenames, no marketing language, present tense, explain *why* not *what*.
+- **Update docs in the same change as the source.** When public APIs, contracts, configuration, build steps, security behavior, event shapes, value conversion, status mapping, or lifecycle rules change, the affected docs (`gateway.md`, `docs/`, client READMEs, design docs) must change in the same commit. Don't leave stale prose describing old behavior.
+
+## Source Update Workflow
+
+When source code changes, build and test the affected component before reporting work done. If the change crosses component boundaries, build each affected component — don't rely on a single top-level build:
+
+| Changed area | Required verification |
+|---|---|
+| Contracts or `.proto` files | regenerate generated code, then build gateway, worker, and every generated client touched by the contract |
+| Gateway server, sessions, workers, gRPC, dashboard, metrics | `dotnet build src/MxGateway.Server` and run affected gateway / fake-worker tests |
+| Worker IPC, STA, MXAccess, conversion | `dotnet build src/MxGateway.Worker -p:Platform=x86` and run worker tests |
+| .NET client | `dotnet build clients/dotnet/MxGateway.Client.sln` and run its tests |
+| Go client | `gofmt`, `go build ./...`, `go test ./...` from `clients/go` |
+| Rust client | `cargo fmt`, `cargo check --workspace`, `cargo test --workspace`, `cargo clippy --all-targets -- -D warnings` from `clients/rust` |
+| Python client | `python -m pytest` from `clients/python` |
+| Java client | `gradle test` from `clients/java` |
+| Integration tests | run only when MXAccess COM, provider state, and external services are available; otherwise document why skipped |
+
+## Design Sources To Consult Before Non-Trivial Changes
+
+- `gateway.md` — top-level architecture, command/event surface, IPC envelope, STA thread model, fault handling.
+- `glauth.md` — local LDAP server (GLAuth on `localhost:3893`, base DN `dc=lmxopcua,dc=local`) used for dev authn. Pre-provisioned users (`admin/admin123`, `readonly/readonly123`, etc.) and the role→capability mapping live there.
+- `docs/DesignDecisions.md` — v1 choices (MXAccess COM target `LMXProxyServerClass` from `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`, API-key-in-SQLite auth, fail-fast event backpressure, etc.).
+- `docs/GatewayProcessDesign.md`, `docs/MxAccessWorkerInstanceDesign.md`, `docs/WorkerFrameProtocol.md`, `docs/WorkerProcessLauncher.md` — detailed component designs.
+- `docs/GatewayConfiguration.md` — full `MxGateway:*` options bound by `GatewayOptions` and validated at startup by `GatewayOptionsValidator`.
+- `docs/GatewayTesting.md` — fake worker harness, live MXAccess smoke, parity matrix, cross-language smoke matrix.
+- `docs/ToolchainLinks.md` — installed compiler/SDK paths on this dev box (.NET 10.0.201, Go 1.26.2, Rust 1.95, Python 3.12.10, Temurin 21, protoc 34.1, etc.).
+
+External analysis sources referenced by design docs:
+
+- `C:\Users\dohertj2\Desktop\mxaccess` — MXAccess analysis project. Key files: `docs/MXAccess-Public-API.md` (COM class, ProgID, CLSID, method list, event signatures, `MxDataType`, `MxStatus`, `MXSTATUS_PROXY`), `docs/MXAccess-Reverse-Engineering.md` (installed runtime path, x86 COM constraints), `docs/Current-Sprint-State.md` (parity gaps), `src/MxTraceHarness/` (x86 harness using the real COM interop), `captures/` and `analysis/` (observed native behavior).
+- `C:\Users\dohertj2\Desktop\lmxopcua\gr` — Galaxy Repository (`ZB` SQL DB) notes. Key files: `connectioninfo.md`, `layout.md`, `schema.md`, `queries/hierarchy.sql`, `queries/attributes.sql`, `queries/attributes_extended.sql`, `queries/change_detection.sql`. Connection is SQL Server `localhost`, database `ZB`, Windows Auth.
+
+## Authentication
+
+Gateway gRPC clients authenticate with an API key in metadata: `authorization: Bearer mxgw_<key-id>_<secret>`. Keys are stored hashed (with a peppered SHA) in a gateway-owned SQLite DB (default `C:\ProgramData\MxGateway\gateway-auth.db`). Scopes (`session`, `invoke`, `event`, `metadata`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/MxGateway.Server/Security/Authentication/`.
+
+Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` binds against `MxGateway:Ldap` and maps the user's LDAP groups to `Admin` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `__Host-MxGatewayDashboard` cookie. SignalR hubs at `/hubs/{snapshot,alarms,events}` accept either the cookie or a 30-minute bearer minted at `/hubs/token`. `Dashboard:AllowAnonymousLocalhost` bypasses auth on loopback when enabled.
+
+## 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.

clients/dotnet/DotnetClientDesign.md

@@ -6,8 +6,8 @@ Provide an idiomatic .NET 10 C# client library for MXAccess Gateway, plus a test
 CLI and unit tests. This client is for modern .NET callers and must not load
 MXAccess COM.
 
-Follow the [C# Style Guide](./style-guides/CSharpStyleGuide.md) for
-handwritten code and the [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)
+Follow the [C# Style Guide](../../docs/style-guides/CSharpStyleGuide.md) for
+handwritten code and the [Protobuf Style Guide](../../docs/style-guides/ProtobufStyleGuide.md)
 for generated contract inputs.
 
 ## Projects
@@ -16,9 +16,9 @@ Recommended layout:
 
 ```text
 clients/dotnet/
-  MxGateway.Client.sln
-  MxGateway.Client/
-    MxGateway.Client.csproj
+  ZB.MOM.WW.MxGateway.Client.slnx
+  ZB.MOM.WW.MxGateway.Client/
+    ZB.MOM.WW.MxGateway.Client.csproj
     GatewayClient.cs
     MxGatewaySession.cs
     MxGatewayClientOptions.cs
@@ -26,14 +26,14 @@ clients/dotnet/
     Conversion/
     Errors/
     Generated/
-  MxGateway.Client.Cli/
-    MxGateway.Client.Cli.csproj
+  ZB.MOM.WW.MxGateway.Client.Cli/
+    ZB.MOM.WW.MxGateway.Client.Cli.csproj
     Program.cs
     Commands/
-  MxGateway.Client.Tests/
-    MxGateway.Client.Tests.csproj
-  MxGateway.Client.IntegrationTests/
-    MxGateway.Client.IntegrationTests.csproj
+  ZB.MOM.WW.MxGateway.Client.Tests/
+    ZB.MOM.WW.MxGateway.Client.Tests.csproj
+  ZB.MOM.WW.MxGateway.Client.IntegrationTests/
+    ZB.MOM.WW.MxGateway.Client.IntegrationTests.csproj
 ```
 
 Target framework:
@@ -43,7 +43,7 @@ Target framework:
 ```
 
 The scaffold uses a project reference to
-`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated protobuf and
+`src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj` for generated protobuf and
 gRPC types. `clients/dotnet/generated` remains reserved for client-local
 generator output if the .NET client later needs to decouple from the contracts
 project.
@@ -166,7 +166,7 @@ reply.EnsureMxAccessSuccess();
 
 ## Test CLI
 
-Project: `MxGateway.Client.Cli`.
+Project: `ZB.MOM.WW.MxGateway.Client.Cli`.
 
 Command examples:
 
@@ -211,3 +211,10 @@ MXGATEWAY_TEST_ITEM=<item>
 
 Integration smoke should open, register, add, advise, stream for bounded time,
 and close.
+
+## Related Documentation
+
+- [Client Libraries Detailed Design](../../docs/ClientLibrariesDesign.md)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [C# Style Guide](../../docs/style-guides/CSharpStyleGuide.md)

clients/dotnet/MxGateway.Client.Cli/IMxGatewayCliClient.cs

@@ -1,39 +0,0 @@
-using MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
-
-namespace MxGateway.Client.Cli;
-
-public interface IMxGatewayCliClient : IAsyncDisposable
-{
-    Task<OpenSessionReply> OpenSessionAsync(
-        OpenSessionRequest request,
-        CancellationToken cancellationToken);
-
-    Task<CloseSessionReply> CloseSessionAsync(
-        CloseSessionRequest request,
-        CancellationToken cancellationToken);
-
-    Task<MxCommandReply> InvokeAsync(
-        MxCommandRequest request,
-        CancellationToken cancellationToken);
-
-    IAsyncEnumerable<MxEvent> StreamEventsAsync(
-        StreamEventsRequest request,
-        CancellationToken cancellationToken);
-
-    Task<TestConnectionReply> GalaxyTestConnectionAsync(
-        TestConnectionRequest request,
-        CancellationToken cancellationToken);
-
-    Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
-        GetLastDeployTimeRequest request,
-        CancellationToken cancellationToken);
-
-    Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
-        DiscoverHierarchyRequest request,
-        CancellationToken cancellationToken);
-
-    IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
-        WatchDeployEventsRequest request,
-        CancellationToken cancellationToken);
-}

clients/dotnet/MxGateway.Client.Cli/MxGatewayCliSecretRedactor.cs

@@ -1,14 +0,0 @@
-namespace MxGateway.Client.Cli;
-
-internal static class MxGatewayCliSecretRedactor
-{
-    public static string Redact(string value, string? apiKey)
-    {
-        if (string.IsNullOrEmpty(value) || string.IsNullOrEmpty(apiKey))
-        {
-            return value;
-        }
-
-        return value.Replace(apiKey, "[redacted]", StringComparison.Ordinal);
-    }
-}

clients/dotnet/MxGateway.Client.Tests/FakeGatewayTransport.cs

@@ -1,107 +0,0 @@
-using Grpc.Core;
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client.Tests;
-
-internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMxGatewayClientTransport
-{
-    private readonly Queue<MxCommandReply> _invokeReplies = new();
-    private readonly List<MxEvent> _events = [];
-
-    public MxGatewayClientOptions Options { get; } = options;
-
-    public MxAccessGateway.MxAccessGatewayClient? RawClient => null;
-
-    public List<(OpenSessionRequest Request, CallOptions CallOptions)> OpenSessionCalls { get; } = [];
-
-    public List<(CloseSessionRequest Request, CallOptions CallOptions)> CloseSessionCalls { get; } = [];
-
-    public List<(MxCommandRequest Request, CallOptions CallOptions)> InvokeCalls { get; } = [];
-
-    public List<(StreamEventsRequest Request, CallOptions CallOptions)> StreamEventsCalls { get; } = [];
-
-    public OpenSessionReply OpenSessionReply { get; set; } = new()
-    {
-        SessionId = "session-fixture",
-        BackendName = "mxaccess-worker",
-        GatewayProtocolVersion = 1,
-        WorkerProtocolVersion = 1,
-        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
-    };
-
-    public CloseSessionReply CloseSessionReply { get; set; } = new()
-    {
-        SessionId = "session-fixture",
-        FinalState = SessionState.Closed,
-        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
-    };
-
-    public Queue<Exception> OpenSessionExceptions { get; } = new();
-
-    public Queue<Exception> CloseSessionExceptions { get; } = new();
-
-    public Queue<Exception> InvokeExceptions { get; } = new();
-
-    public Task<OpenSessionReply> OpenSessionAsync(
-        OpenSessionRequest request,
-        CallOptions callOptions)
-    {
-        OpenSessionCalls.Add((request, callOptions));
-        if (OpenSessionExceptions.TryDequeue(out Exception? exception))
-        {
-            throw exception;
-        }
-
-        return Task.FromResult(OpenSessionReply);
-    }
-
-    public Task<CloseSessionReply> CloseSessionAsync(
-        CloseSessionRequest request,
-        CallOptions callOptions)
-    {
-        CloseSessionCalls.Add((request, callOptions));
-        if (CloseSessionExceptions.TryDequeue(out Exception? exception))
-        {
-            throw exception;
-        }
-
-        return Task.FromResult(CloseSessionReply);
-    }
-
-    public Task<MxCommandReply> InvokeAsync(
-        MxCommandRequest request,
-        CallOptions callOptions)
-    {
-        InvokeCalls.Add((request, callOptions));
-        if (InvokeExceptions.TryDequeue(out Exception? exception))
-        {
-            throw exception;
-        }
-
-        return Task.FromResult(_invokeReplies.Dequeue());
-    }
-
-    public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
-        StreamEventsRequest request,
-        CallOptions callOptions)
-    {
-        StreamEventsCalls.Add((request, callOptions));
-
-        foreach (MxEvent gatewayEvent in _events)
-        {
-            callOptions.CancellationToken.ThrowIfCancellationRequested();
-            await Task.Yield();
-            yield return gatewayEvent;
-        }
-    }
-
-    public void AddInvokeReply(MxCommandReply reply)
-    {
-        _invokeReplies.Enqueue(reply);
-    }
-
-    public void AddEvent(MxEvent gatewayEvent)
-    {
-        _events.Add(gatewayEvent);
-    }
-}

clients/dotnet/MxGateway.Client.sln

@@ -1,76 +0,0 @@
-
-Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 17
-VisualStudioVersion = 17.0.31903.59
-MinimumVisualStudioVersion = 10.0.40219.1
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client", "MxGateway.Client\MxGateway.Client.csproj", "{7CF9ED88-1F32-4040-BEB1-D0902E304C70}"
-EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Contracts", "..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj", "{9AB807A8-0469-40F7-A000-D240F36B6E5D}"
-EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Cli", "MxGateway.Client.Cli\MxGateway.Client.Cli.csproj", "{EB061E77-2475-4322-9257-3F2456DD141C}"
-EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MxGateway.Client.Tests", "MxGateway.Client.Tests\MxGateway.Client.Tests.csproj", "{B77B5A8E-0C53-4419-9BCD-227C9753A074}"
-EndProject
-Global
-	GlobalSection(SolutionConfigurationPlatforms) = preSolution
-		Debug|Any CPU = Debug|Any CPU
-		Debug|x64 = Debug|x64
-		Debug|x86 = Debug|x86
-		Release|Any CPU = Release|Any CPU
-		Release|x64 = Release|x64
-		Release|x86 = Release|x86
-	EndGlobalSection
-	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x64.Build.0 = Debug|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Debug|x86.Build.0 = Debug|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|Any CPU.Build.0 = Release|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.ActiveCfg = Release|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x64.Build.0 = Release|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.ActiveCfg = Release|Any CPU
-		{7CF9ED88-1F32-4040-BEB1-D0902E304C70}.Release|x86.Build.0 = Release|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x64.Build.0 = Debug|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Debug|x86.Build.0 = Debug|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|Any CPU.Build.0 = Release|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.ActiveCfg = Release|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x64.Build.0 = Release|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.ActiveCfg = Release|Any CPU
-		{9AB807A8-0469-40F7-A000-D240F36B6E5D}.Release|x86.Build.0 = Release|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x64.Build.0 = Debug|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Debug|x86.Build.0 = Debug|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|Any CPU.Build.0 = Release|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.ActiveCfg = Release|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x64.Build.0 = Release|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.ActiveCfg = Release|Any CPU
-		{EB061E77-2475-4322-9257-3F2456DD141C}.Release|x86.Build.0 = Release|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x64.Build.0 = Debug|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Debug|x86.Build.0 = Debug|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|Any CPU.Build.0 = Release|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.ActiveCfg = Release|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x64.Build.0 = Release|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.ActiveCfg = Release|Any CPU
-		{B77B5A8E-0C53-4419-9BCD-227C9753A074}.Release|x86.Build.0 = Release|Any CPU
-	EndGlobalSection
-	GlobalSection(SolutionProperties) = preSolution
-		HideSolutionNode = FALSE
-	EndGlobalSection
-EndGlobal

clients/dotnet/MxGateway.Client/IGalaxyRepositoryClientTransport.cs

@@ -1,27 +0,0 @@
-using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
-
-namespace MxGateway.Client;
-
-internal interface IGalaxyRepositoryClientTransport
-{
-    MxGatewayClientOptions Options { get; }
-
-    GalaxyRepository.GalaxyRepositoryClient? RawClient { get; }
-
-    Task<TestConnectionReply> TestConnectionAsync(
-        TestConnectionRequest request,
-        CallOptions callOptions);
-
-    Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
-        GetLastDeployTimeRequest request,
-        CallOptions callOptions);
-
-    Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
-        DiscoverHierarchyRequest request,
-        CallOptions callOptions);
-
-    IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
-        WatchDeployEventsRequest request,
-        CallOptions callOptions);
-}

clients/dotnet/MxGateway.Client/IMxGatewayClientTransport.cs

@@ -1,27 +0,0 @@
-using Grpc.Core;
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-internal interface IMxGatewayClientTransport
-{
-    MxGatewayClientOptions Options { get; }
-
-    MxAccessGateway.MxAccessGatewayClient? RawClient { get; }
-
-    Task<OpenSessionReply> OpenSessionAsync(
-        OpenSessionRequest request,
-        CallOptions callOptions);
-
-    Task<CloseSessionReply> CloseSessionAsync(
-        CloseSessionRequest request,
-        CallOptions callOptions);
-
-    Task<MxCommandReply> InvokeAsync(
-        MxCommandRequest request,
-        CallOptions callOptions);
-
-    IAsyncEnumerable<MxEvent> StreamEventsAsync(
-        StreamEventsRequest request,
-        CallOptions callOptions);
-}

clients/dotnet/MxGateway.Client/MxAccessException.cs

@@ -1,24 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public sealed class MxAccessException : MxGatewayCommandException
-{
-    public MxAccessException(
-        string message,
-        MxCommandReply reply,
-        Exception? innerException = null)
-        : base(
-            message,
-            reply.SessionId,
-            reply.CorrelationId,
-            reply.ProtocolStatus,
-            reply.HasHresult ? reply.Hresult : null,
-            reply.Statuses.ToArray(),
-            innerException)
-    {
-        Reply = reply;
-    }
-
-    public MxCommandReply Reply { get; }
-}

clients/dotnet/MxGateway.Client/MxGatewayAuthenticationException.cs

@@ -1,25 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public sealed class MxGatewayAuthenticationException : MxGatewayException
-{
-    public MxGatewayAuthenticationException(
-        string message,
-        string? sessionId = null,
-        string? correlationId = null,
-        ProtocolStatus? protocolStatus = null,
-        int? hResult = null,
-        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
-        : base(
-            message,
-            sessionId,
-            correlationId,
-            protocolStatus,
-            hResult,
-            statuses ?? [],
-            innerException)
-    {
-    }
-}

clients/dotnet/MxGateway.Client/MxGatewayAuthorizationException.cs

@@ -1,25 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public sealed class MxGatewayAuthorizationException : MxGatewayException
-{
-    public MxGatewayAuthorizationException(
-        string message,
-        string? sessionId = null,
-        string? correlationId = null,
-        ProtocolStatus? protocolStatus = null,
-        int? hResult = null,
-        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
-        : base(
-            message,
-            sessionId,
-            correlationId,
-            protocolStatus,
-            hResult,
-            statuses ?? [],
-            innerException)
-    {
-    }
-}

clients/dotnet/MxGateway.Client/MxGatewayCommandException.cs

@@ -1,25 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public class MxGatewayCommandException : MxGatewayException
-{
-    public MxGatewayCommandException(
-        string message,
-        string? sessionId = null,
-        string? correlationId = null,
-        ProtocolStatus? protocolStatus = null,
-        int? hResult = null,
-        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
-        : base(
-            message,
-            sessionId,
-            correlationId,
-            protocolStatus,
-            hResult,
-            statuses ?? [],
-            innerException)
-    {
-    }
-}

clients/dotnet/MxGateway.Client/MxGatewayException.cs

@@ -1,45 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public class MxGatewayException : Exception
-{
-    public MxGatewayException(string message)
-        : base(message)
-    {
-        Statuses = [];
-    }
-
-    public MxGatewayException(string message, Exception? innerException)
-        : base(message, innerException)
-    {
-        Statuses = [];
-    }
-
-    public MxGatewayException(
-        string message,
-        string? sessionId,
-        string? correlationId,
-        ProtocolStatus? protocolStatus,
-        int? hResult,
-        IReadOnlyList<MxStatusProxy> statuses,
-        Exception? innerException = null)
-        : base(message, innerException)
-    {
-        SessionId = sessionId;
-        CorrelationId = correlationId;
-        ProtocolStatus = protocolStatus;
-        HResultCode = hResult;
-        Statuses = statuses;
-    }
-
-    public string? SessionId { get; }
-
-    public string? CorrelationId { get; }
-
-    public ProtocolStatus? ProtocolStatus { get; }
-
-    public int? HResultCode { get; }
-
-    public IReadOnlyList<MxStatusProxy> Statuses { get; }
-}

clients/dotnet/MxGateway.Client/MxGatewaySessionException.cs

@@ -1,25 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public sealed class MxGatewaySessionException : MxGatewayException
-{
-    public MxGatewaySessionException(
-        string message,
-        string? sessionId = null,
-        string? correlationId = null,
-        ProtocolStatus? protocolStatus = null,
-        int? hResult = null,
-        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
-        : base(
-            message,
-            sessionId,
-            correlationId,
-            protocolStatus,
-            hResult,
-            statuses ?? [],
-            innerException)
-    {
-    }
-}

clients/dotnet/MxGateway.Client/MxGatewayWorkerException.cs

@@ -1,25 +0,0 @@
-using MxGateway.Contracts.Proto;
-
-namespace MxGateway.Client;
-
-public sealed class MxGatewayWorkerException : MxGatewayException
-{
-    public MxGatewayWorkerException(
-        string message,
-        string? sessionId = null,
-        string? correlationId = null,
-        ProtocolStatus? protocolStatus = null,
-        int? hResult = null,
-        IReadOnlyList<MxStatusProxy>? statuses = null,
-        Exception? innerException = null)
-        : base(
-            message,
-            sessionId,
-            correlationId,
-            protocolStatus,
-            hResult,
-            statuses ?? [],
-            innerException)
-    {
-    }
-}

clients/dotnet/MxGateway.Client/Properties/AssemblyInfo.cs

@@ -1,3 +0,0 @@
-using System.Runtime.CompilerServices;
-
-[assembly: InternalsVisibleTo("MxGateway.Client.Tests")]

clients/dotnet/README.md

@@ -7,11 +7,11 @@ CLI, and unit tests.
 
 | Project | Purpose |
 |---------|---------|
-| `MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
-| `MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
-| `MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
+| `ZB.MOM.WW.MxGateway.Client` | .NET 10 library entry point, raw gRPC calls, and session helpers. |
+| `ZB.MOM.WW.MxGateway.Client.Cli` | Test CLI for smoke and diagnostic commands. |
+| `ZB.MOM.WW.MxGateway.Client.Tests` | Unit tests for client options, generated contract wiring, auth metadata, session helpers, cancellation, and event streaming. |
 
-The projects reference `src/MxGateway.Contracts/MxGateway.Contracts.csproj` so
+The projects reference `src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj` so
 the client compiles against the same generated protobuf and gRPC types as the
 gateway. `clients/dotnet/generated` remains reserved for generator output if a
 future client build switches to client-local `Grpc.Tools` generation.
@@ -19,8 +19,8 @@ future client build switches to client-local `Grpc.Tools` generation.
 ## Build And Test
 
 ```powershell
-dotnet build clients/dotnet/MxGateway.Client.sln
-dotnet test clients/dotnet/MxGateway.Client.sln --no-build
+dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx
+dotnet test clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx --no-build
 ```
 
 ## Packaging
@@ -29,8 +29,8 @@ 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
+dotnet pack clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
+dotnet publish clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
 ```
 
 The library package references the shared contracts project at build time. The
@@ -39,11 +39,11 @@ 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
+`src/ZB.MOM.WW.MxGateway.Contracts/Generated`. Regenerate those files through the
 contracts project:
 
 ```powershell
-dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+dotnet build src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj
 ```
 
 ## Client Usage
@@ -117,15 +117,15 @@ reply.
 The test CLI supports deterministic JSON output for automation:
 
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- version --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- open-session --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- register --session-id <id> --client-name mxgw-dotnet-cli --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- add-item --session-id <id> --server-handle 1 --item Area001.Pump001.Speed --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- advise --session-id <id> --server-handle 1 --item-handle 1 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- write2 --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --timestamp 2026-01-01T00:00:00Z --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- stream-events --session-id <id> --max-events 1 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 
 `smoke` opens a session, registers a client, adds one item, advises it,
@@ -164,12 +164,25 @@ foreach (GalaxyObject galaxyObject in objects)
 }
 ```
 
+Use `DiscoverHierarchyOptions` to request a server-side slice without pulling
+the full Galaxy:
+
+```csharp
+IReadOnlyList<GalaxyObject> pumps = await repository.DiscoverHierarchyAsync(
+    new DiscoverHierarchyOptions
+    {
+        RootContainedPath = "Area1/Line3",
+        TagNameGlob = "Pump_*",
+        IncludeAttributes = false,
+    });
+```
+
 The CLI exposes the same operations:
 
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-last-deploy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-test-connection --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-last-deploy --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-discover --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
 ```
 
 ### Watching deploy events
@@ -204,15 +217,15 @@ await foreach (DeployEvent evt in repository.WatchDeployEventsAsync(
 The CLI counterpart streams events until Ctrl+C (or `--max-events`):
 
 ```powershell
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T14:30:00Z --json
-dotnet run --project clients/dotnet/MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --max-events 5 --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --last-seen-deploy-time 2026-04-28T14:30:00Z --json
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- galaxy-watch --endpoint http://localhost:5000 --api-key-env MXGATEWAY_API_KEY --max-events 5 --json
 ```
 
 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
+dotnet run --project clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli -- smoke --endpoint https://ZB.MOM.WW.MxGateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name ZB.MOM.WW.MxGateway.example.local --api-key-env MXGATEWAY_API_KEY --item Area001.Pump001.Speed --json
 ```
 
 ## Integration Checks
@@ -224,11 +237,11 @@ $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'http://localhost:5000'
 $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
+dotnet run --project clients/dotnet/ZB.MOM.WW.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)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [.NET Client Detailed Design](./DotnetClientDesign.md)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/CliArguments.cs

@@ -1,12 +1,15 @@
 using System.Globalization;
 
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 
+/// <summary>Parses command-line arguments into flags and named values.</summary>
 internal sealed class CliArguments
 {
     private readonly Dictionary<string, string> _values = new(StringComparer.OrdinalIgnoreCase);
     private readonly HashSet<string> _flags = new(StringComparer.OrdinalIgnoreCase);
 
+    /// <summary>Initializes a new instance by parsing the given command-line arguments.</summary>
+    /// <param name="args">Unparsed command-line arguments; flags prefixed with '--' and values follow their flag.</param>
     public CliArguments(IEnumerable<string> args)
     {
         string? pendingName = null;
@@ -39,11 +42,15 @@ internal sealed class CliArguments
         }
     }
 
+    /// <summary>Returns whether the named flag was present in the arguments.</summary>
+    /// <param name="name">The flag name (without '--' prefix).</param>
     public bool HasFlag(string name)
     {
         return _flags.Contains(name);
     }
 
+    /// <summary>Returns the value for a named argument, or <c>null</c> if absent.</summary>
+    /// <param name="name">The argument name (without '--' prefix).</param>
     public string? GetOptional(string name)
     {
         return _values.TryGetValue(name, out string? value)
@@ -51,6 +58,8 @@ internal sealed class CliArguments
             : null;
     }
 
+    /// <summary>Returns the value for a required named argument, or throws if absent.</summary>
+    /// <param name="name">The argument name (without '--' prefix).</param>
     public string GetRequired(string name)
     {
         string? value = GetOptional(name);
@@ -62,6 +71,9 @@ internal sealed class CliArguments
         return value;
     }
 
+    /// <summary>Parses and returns an int32 argument, or the default value if absent.</summary>
+    /// <param name="name">The argument name (without '--' prefix).</param>
+    /// <param name="defaultValue">The default value if the argument is absent; if <c>null</c>, the argument is required.</param>
     public int GetInt32(string name, int? defaultValue = null)
     {
         string? value = GetOptional(name);
@@ -78,6 +90,9 @@ internal sealed class CliArguments
         return int.Parse(value, CultureInfo.InvariantCulture);
     }
 
+    /// <summary>Parses and returns a uint32 argument, or the default value if absent.</summary>
+    /// <param name="name">The argument name (without '--' prefix).</param>
+    /// <param name="defaultValue">The default value if the argument is absent.</param>
     public uint GetUInt32(string name, uint defaultValue)
     {
         string? value = GetOptional(name);
@@ -86,6 +101,9 @@ internal sealed class CliArguments
             : uint.Parse(value, CultureInfo.InvariantCulture);
     }
 
+    /// <summary>Parses and returns a uint64 argument, or the default value if absent.</summary>
+    /// <param name="name">The argument name (without '--' prefix).</param>
+    /// <param name="defaultValue">The default value if the argument is absent.</param>
     public ulong GetUInt64(string name, ulong defaultValue)
     {
         string? value = GetOptional(name);
@@ -94,6 +112,9 @@ internal sealed class CliArguments
             : ulong.Parse(value, CultureInfo.InvariantCulture);
     }
 
+    /// <summary>Parses and returns a TimeSpan argument, or the default value if absent. Supports "ms", "s", and standard TimeSpan format.</summary>
+    /// <param name="name">The argument name (without '--' prefix).</param>
+    /// <param name="defaultValue">The default value if the argument is absent.</param>
     public TimeSpan GetDuration(string name, TimeSpan defaultValue)
     {
         string? value = GetOptional(name);

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/IMxGatewayCliClient.cs

@@ -0,0 +1,87 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
+
+public interface IMxGatewayCliClient : IAsyncDisposable
+{
+    /// <summary>
+    /// Opens a new gateway session.
+    /// </summary>
+    /// <param name="request">Session open request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The session open reply.</returns>
+    Task<OpenSessionReply> OpenSessionAsync(
+        OpenSessionRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Closes an open gateway session.
+    /// </summary>
+    /// <param name="request">Session close request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The session close reply.</returns>
+    Task<CloseSessionReply> CloseSessionAsync(
+        CloseSessionRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Invokes an MXAccess command on the session.
+    /// </summary>
+    /// <param name="request">The command request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The command reply.</returns>
+    Task<MxCommandReply> InvokeAsync(
+        MxCommandRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Streams events from the gateway session.
+    /// </summary>
+    /// <param name="request">The stream events request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>An async enumerable of events.</returns>
+    IAsyncEnumerable<MxEvent> StreamEventsAsync(
+        StreamEventsRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Tests connection to the Galaxy Repository.
+    /// </summary>
+    /// <param name="request">The connection test request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The connection test reply.</returns>
+    Task<TestConnectionReply> GalaxyTestConnectionAsync(
+        TestConnectionRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Gets the last deployment time from the Galaxy Repository.
+    /// </summary>
+    /// <param name="request">The last deploy time request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The last deploy time reply.</returns>
+    Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Discovers the Galaxy Repository hierarchy.
+    /// </summary>
+    /// <param name="request">The discover hierarchy request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The discover hierarchy reply.</returns>
+    Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Watches for deployment events from the Galaxy Repository.
+    /// </summary>
+    /// <param name="request">The watch deploy events request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>An async enumerable of deployment events.</returns>
+    IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CancellationToken cancellationToken);
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayCliClientAdapter.cs

@@ -1,14 +1,18 @@
-using MxGateway.Client;
-using MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 
 internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
 {
     private readonly MxGatewayClient _client;
     private readonly Lazy<GalaxyRepositoryClient> _galaxyClient;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MxGatewayCliClientAdapter"/> that bridges the CLI to the gateway client.
+    /// </summary>
+    /// <param name="client">The gateway client to adapt.</param>
     public MxGatewayCliClientAdapter(MxGatewayClient client)
     {
         _client = client;
@@ -16,6 +20,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
             () => GalaxyRepositoryClient.Create(_client.Options));
     }
 
+    /// <inheritdoc />
     public Task<OpenSessionReply> OpenSessionAsync(
         OpenSessionRequest request,
         CancellationToken cancellationToken)
@@ -23,6 +28,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _client.OpenSessionRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public Task<CloseSessionReply> CloseSessionAsync(
         CloseSessionRequest request,
         CancellationToken cancellationToken)
@@ -30,6 +36,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _client.CloseSessionRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public Task<MxCommandReply> InvokeAsync(
         MxCommandRequest request,
         CancellationToken cancellationToken)
@@ -37,6 +44,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _client.InvokeAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CancellationToken cancellationToken)
@@ -44,6 +52,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _client.StreamEventsAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public Task<TestConnectionReply> GalaxyTestConnectionAsync(
         TestConnectionRequest request,
         CancellationToken cancellationToken)
@@ -51,6 +60,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _galaxyClient.Value.TestConnectionRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
         GetLastDeployTimeRequest request,
         CancellationToken cancellationToken)
@@ -58,6 +68,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _galaxyClient.Value.GetLastDeployTimeRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
         DiscoverHierarchyRequest request,
         CancellationToken cancellationToken)
@@ -65,6 +76,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _galaxyClient.Value.DiscoverHierarchyRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CancellationToken cancellationToken)
@@ -72,6 +84,7 @@ internal sealed class MxGatewayCliClientAdapter : IMxGatewayCliClient
         return _galaxyClient.Value.WatchDeployEventsRawAsync(request, cancellationToken);
     }
 
+    /// <inheritdoc />
     public async ValueTask DisposeAsync()
     {
         if (_galaxyClient.IsValueCreated)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayCliSecretRedactor.cs

@@ -0,0 +1,18 @@
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
+
+/// <summary>Utility to redact API keys from error messages for safe output.</summary>
+internal static class MxGatewayCliSecretRedactor
+{
+    /// <summary>Replaces occurrences of the API key in the value with a redacted placeholder.</summary>
+    /// <param name="value">The message text to redact.</param>
+    /// <param name="apiKey">The API key to remove; no redaction if null or empty.</param>
+    public static string Redact(string value, string? apiKey)
+    {
+        if (string.IsNullOrEmpty(value) || string.IsNullOrEmpty(apiKey))
+        {
+            return value;
+        }
+
+        return value.Replace(apiKey, "[redacted]", StringComparison.Ordinal);
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/MxGatewayClientCli.cs

@@ -1,12 +1,13 @@
 using System.Globalization;
 using System.Text.Json;
 using Google.Protobuf;
-using MxGateway.Client;
-using MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
-namespace MxGateway.Client.Cli;
+namespace ZB.MOM.WW.MxGateway.Client.Cli;
 
+/// <summary>Command-line interface for the MXAccess Gateway client, supporting session and command operations.</summary>
 public static class MxGatewayClientCli
 {
     private const uint MaxAggregateEvents = 10_000;
@@ -15,6 +16,10 @@ public static class MxGatewayClientCli
 
     private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
 
+    /// <summary>Runs the CLI synchronously with the given arguments, writing output and errors.</summary>
+    /// <param name="args">Command-line arguments (command name followed by options).</param>
+    /// <param name="standardOutput">TextWriter for command output.</param>
+    /// <param name="standardError">TextWriter for error messages.</param>
     public static int Run(
         string[] args,
         TextWriter standardOutput,
@@ -25,6 +30,11 @@ public static class MxGatewayClientCli
             .GetResult();
     }
 
+    /// <summary>Runs the CLI asynchronously with the given arguments, writing output and errors.</summary>
+    /// <param name="args">Command-line arguments (command name followed by options).</param>
+    /// <param name="standardOutput">TextWriter for command output.</param>
+    /// <param name="standardError">TextWriter for error messages.</param>
+    /// <param name="clientFactory">Optional factory to create the gateway client; defaults to MxGatewayClient.Create.</param>
     public static Task<int> RunAsync(
         string[] args,
         TextWriter standardOutput,
@@ -814,9 +824,7 @@ public static class MxGatewayClientCli
         TextWriter output,
         CancellationToken cancellationToken)
     {
-        DiscoverHierarchyReply reply = await client.GalaxyDiscoverHierarchyAsync(
-                new DiscoverHierarchyRequest(),
-                cancellationToken)
+        DiscoverHierarchyReply reply = await DiscoverAllGalaxyHierarchyAsync(client, cancellationToken)
             .ConfigureAwait(false);
 
         if (arguments.HasFlag("json"))
@@ -834,6 +842,39 @@ public static class MxGatewayClientCli
         return 0;
     }
 
+    private static async Task<DiscoverHierarchyReply> DiscoverAllGalaxyHierarchyAsync(
+        IMxGatewayCliClient client,
+        CancellationToken cancellationToken)
+    {
+        DiscoverHierarchyReply aggregate = new();
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        string pageToken = string.Empty;
+        do
+        {
+            DiscoverHierarchyReply page = await client.GalaxyDiscoverHierarchyAsync(
+                    new DiscoverHierarchyRequest
+                    {
+                        PageSize = 5000,
+                        PageToken = pageToken,
+                    },
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            aggregate.Objects.Add(page.Objects);
+            aggregate.TotalObjectCount = page.TotalObjectCount;
+            pageToken = page.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken)
+                && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy DiscoverHierarchy returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return aggregate;
+    }
+
     private static async Task<int> GalaxyWatchAsync(
         CliArguments arguments,
         IMxGatewayCliClient client,

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/Program.cs

@@ -1,3 +1,3 @@
-using MxGateway.Client.Cli;
+using ZB.MOM.WW.MxGateway.Client.Cli;
 
 return await MxGatewayClientCli.RunAsync(args, Console.Out, Console.Error);

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <ItemGroup>
-    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
+    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client\ZB.MOM.WW.MxGateway.Client.csproj" />
   </ItemGroup>
 
   <PropertyGroup>

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/FakeGalaxyRepositoryTransport.cs

@@ -1,32 +1,75 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
+/// <summary>
+/// Fake Galaxy Repository client transport for testing.
+/// </summary>
 internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions options) : IGalaxyRepositoryClientTransport
 {
+    /// <summary>
+    /// Gets the gateway client options.
+    /// </summary>
     public MxGatewayClientOptions Options { get; } = options;
 
+    /// <summary>
+    /// Gets the raw gRPC client; always null for the fake.
+    /// </summary>
     public GalaxyRepository.GalaxyRepositoryClient? RawClient => null;
 
+    /// <summary>
+    /// Gets the list of TestConnection RPC calls made by the client.
+    /// </summary>
     public List<(TestConnectionRequest Request, CallOptions CallOptions)> TestConnectionCalls { get; } = [];
 
+    /// <summary>
+    /// Gets the list of GetLastDeployTime RPC calls made by the client.
+    /// </summary>
     public List<(GetLastDeployTimeRequest Request, CallOptions CallOptions)> GetLastDeployTimeCalls { get; } = [];
 
+    /// <summary>
+    /// Gets the list of DiscoverHierarchy RPC calls made by the client.
+    /// </summary>
     public List<(DiscoverHierarchyRequest Request, CallOptions CallOptions)> DiscoverHierarchyCalls { get; } = [];
 
+    /// <summary>
+    /// Gets or sets the reply to return from TestConnection; defaults to successful response.
+    /// </summary>
     public TestConnectionReply TestConnectionReply { get; set; } = new() { Ok = true };
 
+    /// <summary>
+    /// Gets or sets the reply to return from GetLastDeployTime; defaults to no deploy time present.
+    /// </summary>
     public GetLastDeployTimeReply GetLastDeployTimeReply { get; set; } = new() { Present = false };
 
+    /// <summary>
+    /// Gets or sets the reply to return from DiscoverHierarchy; defaults to empty response.
+    /// </summary>
     public DiscoverHierarchyReply DiscoverHierarchyReply { get; set; } = new();
 
+    public Queue<DiscoverHierarchyReply> DiscoverHierarchyReplies { get; } = new();
+
+    /// <summary>
+    /// Gets the queue of exceptions to throw from TestConnection; dequeued in FIFO order.
+    /// </summary>
     public Queue<Exception> TestConnectionExceptions { get; } = new();
 
+    /// <summary>
+    /// Gets the queue of exceptions to throw from GetLastDeployTime; dequeued in FIFO order.
+    /// </summary>
     public Queue<Exception> GetLastDeployTimeExceptions { get; } = new();
 
+    /// <summary>
+    /// Gets the queue of exceptions to throw from DiscoverHierarchy; dequeued in FIFO order.
+    /// </summary>
     public Queue<Exception> DiscoverHierarchyExceptions { get; } = new();
 
+    /// <summary>
+    /// Records the request and either throws a queued exception or returns the configured reply.
+    /// </summary>
+    /// <param name="request">The TestConnectionRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
     public Task<TestConnectionReply> TestConnectionAsync(
         TestConnectionRequest request,
         CallOptions callOptions)
@@ -40,6 +83,11 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
         return Task.FromResult(TestConnectionReply);
     }
 
+    /// <summary>
+    /// Records the request and either throws a queued exception or returns the configured reply.
+    /// </summary>
+    /// <param name="request">The GetLastDeployTimeRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
     public Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
         GetLastDeployTimeRequest request,
         CallOptions callOptions)
@@ -53,6 +101,11 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
         return Task.FromResult(GetLastDeployTimeReply);
     }
 
+    /// <summary>
+    /// Records the request and either throws a queued exception or returns the configured reply.
+    /// </summary>
+    /// <param name="request">The DiscoverHierarchyRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
     public Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
         DiscoverHierarchyRequest request,
         CallOptions callOptions)
@@ -63,13 +116,25 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
             throw exception;
         }
 
-        return Task.FromResult(DiscoverHierarchyReply);
+        return Task.FromResult(
+            DiscoverHierarchyReplies.TryDequeue(out DiscoverHierarchyReply? reply)
+                ? reply
+                : DiscoverHierarchyReply);
     }
 
+    /// <summary>
+    /// Gets the list of WatchDeployEvents RPC calls made by the client.
+    /// </summary>
     public List<(WatchDeployEventsRequest Request, CallOptions CallOptions)> WatchDeployEventsCalls { get; } = [];
 
+    /// <summary>
+    /// Gets or sets the list of events to stream from WatchDeployEvents.
+    /// </summary>
     public List<DeployEvent> WatchDeployEvents { get; } = [];
 
+    /// <summary>
+    /// Gets or sets the exception to throw from WatchDeployEvents, if any.
+    /// </summary>
     public Exception? WatchDeployEventsException { get; set; }
 
     /// <summary>
@@ -78,6 +143,11 @@ internal sealed class FakeGalaxyRepositoryTransport(MxGatewayClientOptions optio
     /// </summary>
     public Func<CancellationToken, Task>? WatchDeployEventsBeforeYield { get; set; }
 
+    /// <summary>
+    /// Records the request and streams events, checking for queued exceptions and calling WatchDeployEventsBeforeYield before each event.
+    /// </summary>
+    /// <param name="request">The WatchDeployEventsRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
     public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CallOptions callOptions)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/FakeGatewayTransport.cs

@@ -0,0 +1,241 @@
+using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+/// <summary>
+/// Fake implementation of IMxGatewayClientTransport for testing.
+/// </summary>
+internal sealed class FakeGatewayTransport(MxGatewayClientOptions options) : IMxGatewayClientTransport
+{
+    private readonly Queue<MxCommandReply> _invokeReplies = new();
+    private readonly List<MxEvent> _events = [];
+
+    /// <summary>
+    /// Gets the gateway client options.
+    /// </summary>
+    public MxGatewayClientOptions Options { get; } = options;
+
+    /// <summary>
+    /// Gets null, since this is a test fake without a real gRPC client.
+    /// </summary>
+    public MxAccessGateway.MxAccessGatewayClient? RawClient => null;
+
+    /// <summary>
+    /// Gets the list of captured OpenSessionAsync calls.
+    /// </summary>
+    public List<(OpenSessionRequest Request, CallOptions CallOptions)> OpenSessionCalls { get; } = [];
+
+    /// <summary>
+    /// Gets the list of captured CloseSessionAsync calls.
+    /// </summary>
+    public List<(CloseSessionRequest Request, CallOptions CallOptions)> CloseSessionCalls { get; } = [];
+
+    /// <summary>
+    /// Gets the list of captured InvokeAsync calls.
+    /// </summary>
+    public List<(MxCommandRequest Request, CallOptions CallOptions)> InvokeCalls { get; } = [];
+
+    /// <summary>
+    /// Gets the list of captured StreamEventsAsync calls.
+    /// </summary>
+    public List<(StreamEventsRequest Request, CallOptions CallOptions)> StreamEventsCalls { get; } = [];
+
+    /// <summary>
+    /// Gets the list of captured AcknowledgeAlarmAsync calls.
+    /// </summary>
+    public List<(AcknowledgeAlarmRequest Request, CallOptions CallOptions)> AcknowledgeAlarmCalls { get; } = [];
+
+    /// <summary>
+    /// Gets the list of captured QueryActiveAlarmsAsync calls.
+    /// </summary>
+    public List<(QueryActiveAlarmsRequest Request, CallOptions CallOptions)> QueryActiveAlarmsCalls { get; } = [];
+
+    /// <summary>
+    /// Gets the queue of exceptions to throw from AcknowledgeAlarmAsync.
+    /// </summary>
+    public Queue<Exception> AcknowledgeAlarmExceptions { get; } = new();
+
+    private readonly Queue<AcknowledgeAlarmReply> _acknowledgeReplies = new();
+    private readonly List<ActiveAlarmSnapshot> _activeAlarmSnapshots = [];
+
+    /// <summary>
+    /// Gets or sets the reply to return from OpenSessionAsync.
+    /// </summary>
+    public OpenSessionReply OpenSessionReply { get; set; } = new()
+    {
+        SessionId = "session-fixture",
+        BackendName = "mxaccess-worker",
+        GatewayProtocolVersion = 1,
+        WorkerProtocolVersion = 1,
+        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+    };
+
+    /// <summary>
+    /// Gets or sets the reply to return from CloseSessionAsync.
+    /// </summary>
+    public CloseSessionReply CloseSessionReply { get; set; } = new()
+    {
+        SessionId = "session-fixture",
+        FinalState = SessionState.Closed,
+        ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+    };
+
+    /// <summary>
+    /// Gets the queue of exceptions to throw from OpenSessionAsync.
+    /// </summary>
+    public Queue<Exception> OpenSessionExceptions { get; } = new();
+
+    /// <summary>
+    /// Gets the queue of exceptions to throw from CloseSessionAsync.
+    /// </summary>
+    public Queue<Exception> CloseSessionExceptions { get; } = new();
+
+    /// <summary>
+    /// Gets the queue of exceptions to throw from InvokeAsync.
+    /// </summary>
+    public Queue<Exception> InvokeExceptions { get; } = new();
+
+    /// <summary>
+    /// Verifies that the OpenSessionAsync call is recorded and returns the configured reply.
+    /// </summary>
+    /// <param name="request">The OpenSessionRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    public Task<OpenSessionReply> OpenSessionAsync(
+        OpenSessionRequest request,
+        CallOptions callOptions)
+    {
+        OpenSessionCalls.Add((request, callOptions));
+        if (OpenSessionExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(OpenSessionReply);
+    }
+
+    /// <summary>
+    /// Verifies that the CloseSessionAsync call is recorded and returns the configured reply.
+    /// </summary>
+    /// <param name="request">The CloseSessionRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    public Task<CloseSessionReply> CloseSessionAsync(
+        CloseSessionRequest request,
+        CallOptions callOptions)
+    {
+        CloseSessionCalls.Add((request, callOptions));
+        if (CloseSessionExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(CloseSessionReply);
+    }
+
+    /// <summary>
+    /// Verifies that the InvokeAsync call is recorded and returns the next enqueued reply.
+    /// </summary>
+    /// <param name="request">The MxCommandRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    public Task<MxCommandReply> InvokeAsync(
+        MxCommandRequest request,
+        CallOptions callOptions)
+    {
+        InvokeCalls.Add((request, callOptions));
+        if (InvokeExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(_invokeReplies.Dequeue());
+    }
+
+    /// <summary>
+    /// Verifies that the StreamEventsAsync call is recorded and yields all enqueued events.
+    /// </summary>
+    /// <param name="request">The StreamEventsRequest to process.</param>
+    /// <param name="callOptions">Call options specifying RPC behavior.</param>
+    public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
+        StreamEventsRequest request,
+        CallOptions callOptions)
+    {
+        StreamEventsCalls.Add((request, callOptions));
+
+        foreach (MxEvent gatewayEvent in _events)
+        {
+            callOptions.CancellationToken.ThrowIfCancellationRequested();
+            await Task.Yield();
+            yield return gatewayEvent;
+        }
+    }
+
+    /// <summary>
+    /// Enqueues a reply to be returned from the next InvokeAsync call.
+    /// </summary>
+    /// <param name="reply">The reply to enqueue.</param>
+    public void AddInvokeReply(MxCommandReply reply)
+    {
+        _invokeReplies.Enqueue(reply);
+    }
+
+    /// <summary>
+    /// Enqueues an event to be yielded from StreamEventsAsync.
+    /// </summary>
+    /// <param name="gatewayEvent">The event to enqueue.</param>
+    public void AddEvent(MxEvent gatewayEvent)
+    {
+        _events.Add(gatewayEvent);
+    }
+
+    /// <summary>
+    /// Records the acknowledge call and returns the next enqueued reply (or default).
+    /// </summary>
+    public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CallOptions callOptions)
+    {
+        AcknowledgeAlarmCalls.Add((request, callOptions));
+        if (AcknowledgeAlarmExceptions.TryDequeue(out Exception? exception))
+        {
+            throw exception;
+        }
+
+        return Task.FromResult(_acknowledgeReplies.Count > 0
+            ? _acknowledgeReplies.Dequeue()
+            : new AcknowledgeAlarmReply
+            {
+                CorrelationId = request.ClientCorrelationId,
+                ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+                Status = new MxStatusProxy { Success = 1, Category = MxStatusCategory.Ok },
+            });
+    }
+
+    /// <summary>
+    /// Records the query call and yields each enqueued snapshot.
+    /// </summary>
+    public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
+        QueryActiveAlarmsRequest request,
+        CallOptions callOptions)
+    {
+        QueryActiveAlarmsCalls.Add((request, callOptions));
+
+        foreach (ActiveAlarmSnapshot snapshot in _activeAlarmSnapshots)
+        {
+            callOptions.CancellationToken.ThrowIfCancellationRequested();
+            await Task.Yield();
+            yield return snapshot;
+        }
+    }
+
+    /// <summary>Enqueues an acknowledge reply.</summary>
+    public void AddAcknowledgeReply(AcknowledgeAlarmReply reply)
+    {
+        _acknowledgeReplies.Enqueue(reply);
+    }
+
+    /// <summary>Enqueues a snapshot to be yielded from QueryActiveAlarmsAsync.</summary>
+    public void AddActiveAlarmSnapshot(ActiveAlarmSnapshot snapshot)
+    {
+        _activeAlarmSnapshots.Add(snapshot);
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/GalaxyRepositoryClientTests.cs

@@ -1,11 +1,14 @@
 using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class GalaxyRepositoryClientTests
 {
+    /// <summary>
+    /// Verifies that TestConnectionAsync attaches the API key in request metadata and returns the Ok flag.
+    /// </summary>
     [Fact]
     public async Task TestConnectionAsync_AttachesApiKeyMetadataAndReturnsOkFlag()
     {
@@ -21,6 +24,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal("Bearer test-api-key", call.CallOptions.Headers?.GetValue("authorization"));
     }
 
+    /// <summary>
+    /// Verifies that TestConnectionAsync returns false when the server reports NotOk.
+    /// </summary>
     [Fact]
     public async Task TestConnectionAsync_ReturnsFalseWhenServerReportsNotOk()
     {
@@ -33,6 +39,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.False(ok);
     }
 
+    /// <summary>
+    /// Verifies that GetLastDeployTimeAsync returns null when the server reports not present.
+    /// </summary>
     [Fact]
     public async Task GetLastDeployTimeAsync_ReturnsNullWhenNotPresent()
     {
@@ -46,6 +55,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Single(transport.GetLastDeployTimeCalls);
     }
 
+    /// <summary>
+    /// Verifies that GetLastDeployTimeAsync returns the timestamp when the server reports it present.
+    /// </summary>
     [Fact]
     public async Task GetLastDeployTimeAsync_ReturnsTimestampWhenPresent()
     {
@@ -64,12 +76,17 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal(expected, deployTime!.Value);
     }
 
+    /// <summary>
+    /// Verifies that DiscoverHierarchyAsync returns the objects from the server reply.
+    /// </summary>
     [Fact]
     public async Task DiscoverHierarchyAsync_ReturnsObjectsFromReply()
     {
         FakeGalaxyRepositoryTransport transport = CreateTransport();
-        transport.DiscoverHierarchyReply = new DiscoverHierarchyReply
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
         {
+            NextPageToken = "page-2",
+            TotalObjectCount = 2,
             Objects =
             {
                 new GalaxyObject
@@ -91,12 +108,29 @@ public sealed class GalaxyRepositoryClientTests
                     },
                 },
             },
-        };
+        });
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 13,
+                    TagName = "DelmiaReceiver_002",
+                },
+            },
+        });
         await using GalaxyRepositoryClient client = CreateClient(transport);
 
         IReadOnlyList<GalaxyObject> objects = await client.DiscoverHierarchyAsync();
 
-        GalaxyObject obj = Assert.Single(objects);
+        Assert.Equal(2, objects.Count);
+        Assert.Equal(2, transport.DiscoverHierarchyCalls.Count);
+        Assert.Equal(5000, transport.DiscoverHierarchyCalls[0].Request.PageSize);
+        Assert.Equal("", transport.DiscoverHierarchyCalls[0].Request.PageToken);
+        Assert.Equal("page-2", transport.DiscoverHierarchyCalls[1].Request.PageToken);
+        GalaxyObject obj = objects[0];
         Assert.Equal(12, obj.GobjectId);
         Assert.Equal("DelmiaReceiver_001", obj.TagName);
         GalaxyAttribute attribute = Assert.Single(obj.Attributes);
@@ -104,6 +138,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal("DelmiaReceiver_001.DownloadPath", attribute.FullTagReference);
     }
 
+    /// <summary>
+    /// Verifies that DiscoverHierarchyAsync propagates cancellation tokens to the transport.
+    /// </summary>
     [Fact]
     public async Task DiscoverHierarchyAsync_PropagatesCancellationToTransport()
     {
@@ -121,6 +158,60 @@ public sealed class GalaxyRepositoryClientTests
         Assert.False(call.CallOptions.CancellationToken.IsCancellationRequested);
     }
 
+    /// <summary>
+    /// Verifies that TestConnectionAsync retries on transient gRPC failures.
+    /// </summary>
+    [Fact]
+    public async Task DiscoverHierarchyAsync_WithRepeatedPageToken_ThrowsProtocolError()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+        });
+        transport.DiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            NextPageToken = "7:1",
+        });
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        MxGatewayException exception = await Assert.ThrowsAsync<MxGatewayException>(
+            async () => await client.DiscoverHierarchyAsync());
+
+        Assert.Contains("repeated page token", exception.Message, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task DiscoverHierarchyAsync_WithOptions_MapsTypedFilters()
+    {
+        FakeGalaxyRepositoryTransport transport = CreateTransport();
+        await using GalaxyRepositoryClient client = CreateClient(transport);
+
+        await client.DiscoverHierarchyAsync(new DiscoverHierarchyOptions
+        {
+            RootContainedPath = "Area1/Line3",
+            MaxDepth = 2,
+            CategoryIds = [10, 13],
+            TemplateChainContains = ["Pump"],
+            TagNameGlob = "Pump_*",
+            IncludeAttributes = false,
+            AlarmBearingOnly = true,
+            HistorizedOnly = true,
+        });
+
+        DiscoverHierarchyRequest request = Assert.Single(transport.DiscoverHierarchyCalls).Request;
+        Assert.Equal(DiscoverHierarchyRequest.RootOneofCase.RootContainedPath, request.RootCase);
+        Assert.Equal("Area1/Line3", request.RootContainedPath);
+        Assert.Equal(2, request.MaxDepth);
+        Assert.Equal([10, 13], request.CategoryIds);
+        Assert.Equal(["Pump"], request.TemplateChainContains);
+        Assert.Equal("Pump_*", request.TagNameGlob);
+        Assert.True(request.HasIncludeAttributes);
+        Assert.False(request.IncludeAttributes);
+        Assert.True(request.AlarmBearingOnly);
+        Assert.True(request.HistorizedOnly);
+    }
+
     [Fact]
     public async Task TestConnectionAsync_RetriesOnTransientGrpcFailure()
     {
@@ -135,6 +226,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal(2, transport.TestConnectionCalls.Count);
     }
 
+    /// <summary>
+    /// Verifies that DiscoverHierarchyAsync retries on transient gRPC failures.
+    /// </summary>
     [Fact]
     public async Task DiscoverHierarchyAsync_RetriesOnTransientGrpcFailure()
     {
@@ -148,6 +242,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal(2, transport.DiscoverHierarchyCalls.Count);
     }
 
+    /// <summary>
+    /// Verifies that WatchDeployEventsAsync delivers the bootstrap event.
+    /// </summary>
     [Fact]
     public async Task WatchDeployEventsAsync_DeliversBootstrapEvent()
     {
@@ -181,6 +278,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Null(call.Request.LastSeenDeployTime);
     }
 
+    /// <summary>
+    /// Verifies that WatchDeployEventsAsync delivers multiple events in order.
+    /// </summary>
     [Fact]
     public async Task WatchDeployEventsAsync_DeliversMultipleEventsInOrder()
     {
@@ -216,6 +316,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal(t0, call.Request.LastSeenDeployTime!.ToDateTime());
     }
 
+    /// <summary>
+    /// Verifies that WatchDeployEventsAsync stops iteration cleanly when cancelled.
+    /// </summary>
     [Fact]
     public async Task WatchDeployEventsAsync_CancellationStopsIterationCleanly()
     {
@@ -257,6 +360,9 @@ public sealed class GalaxyRepositoryClientTests
         Assert.Equal(1ul, received[0].Sequence);
     }
 
+    /// <summary>
+    /// Verifies that WatchDeployEventsAsync throws ObjectDisposedException after the client is disposed.
+    /// </summary>
     [Fact]
     public async Task WatchDeployEventsAsync_ThrowsAfterDisposal()
     {
@@ -269,6 +375,9 @@ public sealed class GalaxyRepositoryClientTests
             client.WatchDeployEventsAsync());
     }
 
+    /// <summary>
+    /// Verifies that TestConnectionAsync throws ObjectDisposedException after the client is disposed.
+    /// </summary>
     [Fact]
     public async Task TestConnectionAsync_ThrowsAfterDisposal()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxCommandReplyExtensionsTests.cs

@@ -1,11 +1,12 @@
 using Google.Protobuf;
-using MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class MxCommandReplyExtensionsTests
 {
+    /// <summary>Verifies that successful replies pass both protocol and MxAccess success checks.</summary>
     [Fact]
     public void EnsureSuccess_WithRegisterFixture_ReturnsReply()
     {
@@ -15,6 +16,7 @@ public sealed class MxCommandReplyExtensionsTests
         Assert.Same(reply, reply.EnsureMxAccessSuccess());
     }
 
+    /// <summary>Verifies that MxAccess failures throw with preserved HResult and status details.</summary>
     [Fact]
     public void EnsureMxAccessSuccess_WithFailureFixture_PreservesHResultAndStatuses()
     {
@@ -30,6 +32,7 @@ public sealed class MxCommandReplyExtensionsTests
         Assert.Contains("0x80040200", exception.Message);
     }
 
+    /// <summary>Verifies that session-not-found protocol failures throw the correct gateway exception.</summary>
     [Fact]
     public void EnsureProtocolSuccess_WithSessionFailure_ThrowsSessionException()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientAlarmsTests.cs

@@ -0,0 +1,188 @@
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+/// <summary>
+///     PR E.2 — pins the .NET SDK surface for the new alarm RPCs:
+///     <see cref="MxGatewayClient.AcknowledgeAlarmAsync"/> and
+///     <see cref="MxGatewayClient.QueryActiveAlarmsAsync"/>.
+/// </summary>
+public sealed class MxGatewayClientAlarmsTests
+{
+    [Fact]
+    public async Task AcknowledgeAlarmAsync_RecordsRequestShapeAndReturnsReply()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddAcknowledgeReply(new AcknowledgeAlarmReply
+        {
+            CorrelationId = "corr-1",
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+            Status = new MxStatusProxy
+            {
+                Success = 1,
+                Category = MxStatusCategory.Ok,
+                DetectedBy = MxStatusSource.RespondingLmx,
+            },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+
+        AcknowledgeAlarmReply reply = await client.AcknowledgeAlarmAsync(new AcknowledgeAlarmRequest
+        {
+            ClientCorrelationId = "corr-1",
+            AlarmFullReference = "Tank01.Level.HiHi",
+            Comment = "investigating",
+            OperatorUser = "alice",
+        });
+
+        Assert.Equal(ProtocolStatusCode.Ok, reply.ProtocolStatus.Code);
+        Assert.Equal(MxStatusCategory.Ok, reply.Status.Category);
+
+        var call = Assert.Single(transport.AcknowledgeAlarmCalls);
+        Assert.Equal("Tank01.Level.HiHi", call.Request.AlarmFullReference);
+        Assert.Equal("investigating", call.Request.Comment);
+        Assert.Equal("alice", call.Request.OperatorUser);
+        Assert.Equal("Bearer test-api-key", call.CallOptions.Headers?.GetValue("authorization"));
+    }
+
+    [Fact]
+    public async Task AcknowledgeAlarmAsync_HonorsCancellation()
+    {
+        // Acks are routed through the safe-unary retry pipeline (idempotent at the
+        // MxAccess level), so the transport-side cancellation token is a linked one
+        // rather than the caller's original. Verify cancellation by tripping the source
+        // and asserting the call observes it.
+        using CancellationTokenSource cancellation = new();
+        cancellation.Cancel();
+        FakeGatewayTransport transport = CreateTransport();
+        await using MxGatewayClient client = CreateClient(transport);
+
+        await Assert.ThrowsAnyAsync<OperationCanceledException>(() =>
+            client.AcknowledgeAlarmAsync(
+                new AcknowledgeAlarmRequest
+                {
+                    AlarmFullReference = "Tank01.Level.HiHi",
+                    Comment = string.Empty,
+                    OperatorUser = "alice",
+                },
+                cancellation.Token));
+    }
+
+    [Fact]
+    public async Task AcknowledgeAlarmAsync_MapsUnauthenticated_RpcException_ToTypedException()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AcknowledgeAlarmExceptions.Enqueue(
+            new RpcException(new Status(StatusCode.Unauthenticated, "expired key")));
+        await using MxGatewayClient client = CreateClient(transport);
+
+        // Note: the FakeGatewayTransport surfaces RpcException directly (it does not run
+        // through GrpcMxGatewayClientTransport's mapping); the fake's contract here is to
+        // pass the exception verbatim. RpcException → typed exception mapping is covered
+        // in the GrpcMxGatewayClientTransport-level tests; the SDK-level test pins the
+        // pass-through shape so a future migration to direct mapping won't silently
+        // change observable behaviour.
+        var ex = await Assert.ThrowsAsync<RpcException>(
+            () => client.AcknowledgeAlarmAsync(new AcknowledgeAlarmRequest
+            {
+                AlarmFullReference = "Tank01.Level.HiHi",
+                Comment = string.Empty,
+                OperatorUser = "alice",
+            }));
+        Assert.Equal(StatusCode.Unauthenticated, ex.StatusCode);
+    }
+
+    [Fact]
+    public async Task QueryActiveAlarmsAsync_StreamsEnqueuedSnapshots()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank01.Level.HiHi", AlarmConditionState.Active));
+        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank02.Level.HiHi", AlarmConditionState.ActiveAcked));
+        await using MxGatewayClient client = CreateClient(transport);
+
+        List<ActiveAlarmSnapshot> snapshots = [];
+        await foreach (ActiveAlarmSnapshot snapshot in client.QueryActiveAlarmsAsync(new QueryActiveAlarmsRequest
+        {
+            SessionId = "session-fixture",
+        }))
+        {
+            snapshots.Add(snapshot);
+        }
+
+        Assert.Equal(2, snapshots.Count);
+        Assert.Equal("Tank01.Level.HiHi", snapshots[0].AlarmFullReference);
+        Assert.Equal(AlarmConditionState.Active, snapshots[0].CurrentState);
+        Assert.Equal(AlarmConditionState.ActiveAcked, snapshots[1].CurrentState);
+        Assert.Single(transport.QueryActiveAlarmsCalls);
+    }
+
+    [Fact]
+    public async Task QueryActiveAlarmsAsync_PassesFilterPrefix()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        await using MxGatewayClient client = CreateClient(transport);
+
+        await foreach (ActiveAlarmSnapshot _ in client.QueryActiveAlarmsAsync(new QueryActiveAlarmsRequest
+        {
+            SessionId = "session-fixture",
+            AlarmFilterPrefix = "Tank01.",
+        }))
+        {
+            // no snapshots enqueued; just verifying the request passes through
+        }
+
+        var call = Assert.Single(transport.QueryActiveAlarmsCalls);
+        Assert.Equal("Tank01.", call.Request.AlarmFilterPrefix);
+    }
+
+    [Fact]
+    public async Task QueryActiveAlarmsAsync_HonorsCancellationDuringEnumeration()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank01.Level.HiHi", AlarmConditionState.Active));
+        transport.AddActiveAlarmSnapshot(MakeSnapshot("Tank02.Level.HiHi", AlarmConditionState.Active));
+        await using MxGatewayClient client = CreateClient(transport);
+
+        using CancellationTokenSource cancellation = new();
+        await Assert.ThrowsAsync<OperationCanceledException>(async () =>
+        {
+            await foreach (ActiveAlarmSnapshot _ in client.QueryActiveAlarmsAsync(
+                new QueryActiveAlarmsRequest { SessionId = "session-fixture" },
+                cancellation.Token))
+            {
+                cancellation.Cancel();
+            }
+        });
+    }
+
+    private static ActiveAlarmSnapshot MakeSnapshot(string fullReference, AlarmConditionState state)
+    {
+        return new ActiveAlarmSnapshot
+        {
+            AlarmFullReference = fullReference,
+            SourceObjectReference = fullReference.Split('.')[0],
+            AlarmTypeName = "AnalogLimitAlarm.HiHi",
+            Severity = 750,
+            CurrentState = state,
+            Category = "Process",
+            Description = "Tank high-high level",
+            OriginalRaiseTimestamp = Timestamp.FromDateTime(new DateTime(2026, 5, 1, 12, 0, 0, DateTimeKind.Utc)),
+            LastTransitionTimestamp = Timestamp.FromDateTime(new DateTime(2026, 5, 1, 12, 0, 30, DateTimeKind.Utc)),
+        };
+    }
+
+    private static MxGatewayClient CreateClient(FakeGatewayTransport transport)
+    {
+        return new MxGatewayClient(transport.Options, transport);
+    }
+
+    private static FakeGatewayTransport CreateTransport()
+    {
+        return new FakeGatewayTransport(new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+        });
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientCliTests.cs

@@ -1,12 +1,14 @@
 using Google.Protobuf.WellKnownTypes;
-using MxGateway.Client.Cli;
-using MxGateway.Contracts.Proto;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Client.Cli;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
+/// <summary>Tests for the CLI command interface.</summary>
 public sealed class MxGatewayClientCliTests
 {
+    /// <summary>Verifies that the version command prints compiled protocol versions.</summary>
     [Fact]
     public void Run_Version_PrintsCompiledProtocolVersions()
     {
@@ -16,11 +18,12 @@ public sealed class MxGatewayClientCliTests
         var exitCode = MxGatewayClientCli.Run(["version"], output, error);
 
         Assert.Equal(0, exitCode);
-        Assert.Contains("gateway-protocol=1", output.ToString());
+        Assert.Contains("gateway-protocol=3", output.ToString());
         Assert.Contains("worker-protocol=1", output.ToString());
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>Verifies that the version command with --json flag prints JSON protocol versions.</summary>
     [Fact]
     public async Task RunAsync_VersionJson_PrintsJsonProtocolVersions()
     {
@@ -30,10 +33,11 @@ public sealed class MxGatewayClientCliTests
         int exitCode = await MxGatewayClientCli.RunAsync(["version", "--json"], output, error);
 
         Assert.Equal(0, exitCode);
-        Assert.Contains("\"gatewayProtocolVersion\":1", output.ToString());
+        Assert.Contains("\"gatewayProtocolVersion\":3", output.ToString());
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>Verifies that the write command builds a write request and prints JSON reply.</summary>
     [Fact]
     public async Task RunAsync_Write_BuildsWriteCommandAndPrintsJsonReply()
     {
@@ -78,6 +82,7 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>Verifies that error output redacts sensitive API key values.</summary>
     [Fact]
     public async Task RunAsync_ErrorOutput_RedactsApiKey()
     {
@@ -101,6 +106,7 @@ public sealed class MxGatewayClientCliTests
         Assert.Contains("[redacted]", error.ToString());
     }
 
+    /// <summary>Verifies that stream-events with max-events limit stops output in non-JSON format.</summary>
     [Fact]
     public async Task RunAsync_StreamEvents_WithMaxEventsStopsNonJsonOutput()
     {
@@ -142,6 +148,7 @@ public sealed class MxGatewayClientCliTests
     }
 
 
+    /// <summary>Verifies that smoke command closes opened session when a command fails.</summary>
     [Fact]
     public async Task RunAsync_Smoke_WhenCommandFails_ClosesOpenedSession()
     {
@@ -172,6 +179,7 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal("session-fixture", closeRequest.SessionId);
     }
 
+    /// <summary>Verifies that galaxy-test-connection command prints JSON reply.</summary>
     [Fact]
     public async Task RunAsync_GalaxyTestConnection_PrintsJsonReply()
     {
@@ -201,14 +209,17 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>Verifies that galaxy-discover command prints hierarchy summary.</summary>
     [Fact]
     public async Task RunAsync_GalaxyDiscover_PrintsHierarchySummary()
     {
         using var output = new StringWriter();
         using var error = new StringWriter();
         FakeCliClient fakeClient = new();
-        fakeClient.GalaxyDiscoverHierarchyReply = new DiscoverHierarchyReply
+        fakeClient.GalaxyDiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
         {
+            NextPageToken = "7:1",
+            TotalObjectCount = 2,
             Objects =
             {
                 new GalaxyObject
@@ -227,7 +238,21 @@ public sealed class MxGatewayClientCliTests
                     },
                 },
             },
-        };
+        });
+        fakeClient.GalaxyDiscoverHierarchyReplies.Enqueue(new DiscoverHierarchyReply
+        {
+            TotalObjectCount = 2,
+            Objects =
+            {
+                new GalaxyObject
+                {
+                    GobjectId = 8,
+                    TagName = "DelmiaReceiver_002",
+                    ContainedName = "DelmiaReceiver",
+                    ParentGobjectId = 1,
+                },
+            },
+        });
 
         int exitCode = await MxGatewayClientCli.RunAsync(
             [
@@ -242,14 +267,19 @@ public sealed class MxGatewayClientCliTests
             _ => fakeClient);
 
         Assert.Equal(0, exitCode);
-        Assert.Single(fakeClient.GalaxyDiscoverHierarchyRequests);
+        Assert.Equal(2, fakeClient.GalaxyDiscoverHierarchyRequests.Count);
+        Assert.Equal(5000, fakeClient.GalaxyDiscoverHierarchyRequests[0].PageSize);
+        Assert.Equal("", fakeClient.GalaxyDiscoverHierarchyRequests[0].PageToken);
+        Assert.Equal("7:1", fakeClient.GalaxyDiscoverHierarchyRequests[1].PageToken);
         string text = output.ToString();
-        Assert.Contains("objects=1", text);
+        Assert.Contains("objects=2", text);
         Assert.Contains("DelmiaReceiver_001", text);
+        Assert.Contains("DelmiaReceiver_002", text);
         Assert.Contains("attributes=1", text);
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>Verifies that galaxy-watch command prints text output for deploy events.</summary>
     [Fact]
     public async Task RunAsync_GalaxyWatch_PrintsTextOutputForEvents()
     {
@@ -303,6 +333,7 @@ public sealed class MxGatewayClientCliTests
         Assert.Equal(string.Empty, error.ToString());
     }
 
+    /// <summary>Verifies that galaxy-watch with --json emits one JSON object per event.</summary>
     [Fact]
     public async Task RunAsync_GalaxyWatch_JsonEmitsOneObjectPerEvent()
     {
@@ -337,23 +368,31 @@ public sealed class MxGatewayClientCliTests
         Assert.Contains("\"objectCount\": 99", text);
     }
 
+    /// <summary>Fake CLI client for testing.</summary>
     private sealed class FakeCliClient : IMxGatewayCliClient
     {
+        /// <summary>Queue of invoke replies to return.</summary>
         public Queue<MxCommandReply> InvokeReplies { get; } = new();
 
+        /// <summary>List of received invoke requests.</summary>
         public List<MxCommandRequest> InvokeRequests { get; } = [];
 
+        /// <summary>List of received close session requests.</summary>
         public List<CloseSessionRequest> CloseSessionRequests { get; } = [];
 
+        /// <summary>List of events to yield when streaming.</summary>
         public List<MxEvent> Events { get; } = [];
 
+        /// <summary>Exception to throw on invoke, if any.</summary>
         public Exception? InvokeFailure { get; init; }
 
+        /// <inheritdoc />
         public ValueTask DisposeAsync()
         {
             return ValueTask.CompletedTask;
         }
 
+        /// <inheritdoc />
         public Task<OpenSessionReply> OpenSessionAsync(
             OpenSessionRequest request,
             CancellationToken cancellationToken)
@@ -367,6 +406,7 @@ public sealed class MxGatewayClientCliTests
             });
         }
 
+        /// <inheritdoc />
         public Task<CloseSessionReply> CloseSessionAsync(
             CloseSessionRequest request,
             CancellationToken cancellationToken)
@@ -380,6 +420,7 @@ public sealed class MxGatewayClientCliTests
             });
         }
 
+        /// <inheritdoc />
         public Task<MxCommandReply> InvokeAsync(
             MxCommandRequest request,
             CancellationToken cancellationToken)
@@ -393,6 +434,7 @@ public sealed class MxGatewayClientCliTests
             return Task.FromResult(InvokeReplies.Dequeue());
         }
 
+        /// <inheritdoc />
         public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
             StreamEventsRequest request,
             [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
@@ -405,18 +447,27 @@ public sealed class MxGatewayClientCliTests
             }
         }
 
+        /// <summary>Galaxy test connection reply to return.</summary>
         public TestConnectionReply GalaxyTestConnectionReply { get; set; } = new() { Ok = true };
 
+        /// <summary>Galaxy get last deploy time reply to return.</summary>
         public GetLastDeployTimeReply GalaxyGetLastDeployTimeReply { get; set; } = new() { Present = false };
 
+        /// <summary>Galaxy discover hierarchy reply to return.</summary>
         public DiscoverHierarchyReply GalaxyDiscoverHierarchyReply { get; set; } = new();
 
+        public Queue<DiscoverHierarchyReply> GalaxyDiscoverHierarchyReplies { get; } = new();
+
+        /// <summary>List of received galaxy test connection requests.</summary>
         public List<TestConnectionRequest> GalaxyTestConnectionRequests { get; } = [];
 
+        /// <summary>List of received galaxy get last deploy time requests.</summary>
         public List<GetLastDeployTimeRequest> GalaxyGetLastDeployTimeRequests { get; } = [];
 
+        /// <summary>List of received galaxy discover hierarchy requests.</summary>
         public List<DiscoverHierarchyRequest> GalaxyDiscoverHierarchyRequests { get; } = [];
 
+        /// <inheritdoc />
         public Task<TestConnectionReply> GalaxyTestConnectionAsync(
             TestConnectionRequest request,
             CancellationToken cancellationToken)
@@ -425,6 +476,7 @@ public sealed class MxGatewayClientCliTests
             return Task.FromResult(GalaxyTestConnectionReply);
         }
 
+        /// <inheritdoc />
         public Task<GetLastDeployTimeReply> GalaxyGetLastDeployTimeAsync(
             GetLastDeployTimeRequest request,
             CancellationToken cancellationToken)
@@ -433,18 +485,25 @@ public sealed class MxGatewayClientCliTests
             return Task.FromResult(GalaxyGetLastDeployTimeReply);
         }
 
+        /// <inheritdoc />
         public Task<DiscoverHierarchyReply> GalaxyDiscoverHierarchyAsync(
             DiscoverHierarchyRequest request,
             CancellationToken cancellationToken)
         {
             GalaxyDiscoverHierarchyRequests.Add(request);
-            return Task.FromResult(GalaxyDiscoverHierarchyReply);
+            return Task.FromResult(
+                GalaxyDiscoverHierarchyReplies.TryDequeue(out DiscoverHierarchyReply? reply)
+                    ? reply
+                    : GalaxyDiscoverHierarchyReply);
         }
 
+        /// <summary>List of received galaxy watch deploy events requests.</summary>
         public List<WatchDeployEventsRequest> GalaxyWatchDeployEventsRequests { get; } = [];
 
+        /// <summary>List of deploy events to yield when watching.</summary>
         public List<DeployEvent> GalaxyDeployEvents { get; } = [];
 
+        /// <inheritdoc />
         public async IAsyncEnumerable<DeployEvent> GalaxyWatchDeployEventsAsync(
             WatchDeployEventsRequest request,
             [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientContractInfoTests.cs

@@ -1,9 +1,10 @@
-using MxGateway.Contracts;
+using ZB.MOM.WW.MxGateway.Contracts;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class MxGatewayClientContractInfoTests
 {
+    /// <summary>Verifies that the client's gateway protocol version matches the shared contract definition.</summary>
     [Fact]
     public void GatewayProtocolVersion_MatchesSharedContract()
     {
@@ -12,6 +13,7 @@ public sealed class MxGatewayClientContractInfoTests
             MxGatewayClientContractInfo.GatewayProtocolVersion);
     }
 
+    /// <summary>Verifies that the client's worker protocol version matches the shared contract definition.</summary>
     [Fact]
     public void WorkerProtocolVersion_MatchesSharedContract()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientOptionsTests.cs

@@ -1,7 +1,8 @@
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class MxGatewayClientOptionsTests
 {
+    /// <summary>Verifies that options with valid endpoint and API key pass validation.</summary>
     [Fact]
     public void Validate_WithAbsoluteEndpointAndApiKey_Succeeds()
     {
@@ -14,6 +15,7 @@ public sealed class MxGatewayClientOptionsTests
         options.Validate();
     }
 
+    /// <summary>Verifies that empty API key causes validation to fail.</summary>
     [Fact]
     public void Validate_WithEmptyApiKey_Throws()
     {
@@ -26,6 +28,7 @@ public sealed class MxGatewayClientOptionsTests
         Assert.Throws<ArgumentException>(options.Validate);
     }
 
+    /// <summary>Verifies that invalid retry options cause validation to fail.</summary>
     [Fact]
     public void Validate_WithInvalidRetryOptions_Throws()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayClientSessionTests.cs

@@ -1,10 +1,12 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using Grpc.Core;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
+/// <summary>Tests for MxGatewaySession and client command behavior.</summary>
 public sealed class MxGatewayClientSessionTests
 {
+    /// <summary>Verifies that open session attaches API key metadata and cancellation token.</summary>
     [Fact]
     public async Task OpenSessionRawAsync_AttachesApiKeyMetadataAndCancellation()
     {
@@ -19,6 +21,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(cancellation.Token, call.CallOptions.CancellationToken);
     }
 
+    /// <summary>Verifies that open session returns a session with the raw open reply.</summary>
     [Fact]
     public async Task OpenSessionAsync_ReturnsSessionWithRawOpenReply()
     {
@@ -33,6 +36,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(1234, session.OpenSessionReply.WorkerProcessId);
     }
 
+    /// <summary>Verifies that register builds a register command and returns server handle.</summary>
     [Fact]
     public async Task RegisterAsync_BuildsRegisterCommandAndReturnsServerHandle()
     {
@@ -57,6 +61,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal("fixture-client", call.Request.Command.Register.ClientName);
     }
 
+    /// <summary>Verifies that add item 2 builds a command with the specified context.</summary>
     [Fact]
     public async Task AddItem2Async_BuildsAddItem2CommandWithContext()
     {
@@ -81,6 +86,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal("runtime", request.Command.AddItem2.ItemContext);
     }
 
+    /// <summary>Verifies that write raw builds a write command with the raw value.</summary>
     [Fact]
     public async Task WriteRawAsync_BuildsWriteCommandWithRawValue()
     {
@@ -111,6 +117,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(56, request.Command.Write.UserId);
     }
 
+    /// <summary>Verifies that write 2 raw builds a write 2 command with value and timestamp.</summary>
     [Fact]
     public async Task Write2RawAsync_BuildsWrite2CommandWithValueAndTimestamp()
     {
@@ -138,6 +145,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(56, request.Command.Write2.UserId);
     }
 
+    /// <summary>Verifies that subscribe bulk builds one command and returns per-item results.</summary>
     [Fact]
     public async Task SubscribeBulkAsync_BuildsOneBulkCommandAndReturnsPerItemResults()
     {
@@ -176,6 +184,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(["Area001.Pump001.Speed"], request.Command.SubscribeBulk.TagAddresses);
     }
 
+    /// <summary>Verifies that stream events yields events in the order received from the gateway.</summary>
     [Fact]
     public async Task StreamEventsAsync_YieldsEventsInGatewayOrder()
     {
@@ -206,6 +215,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal("session-fixture", request.SessionId);
     }
 
+    /// <summary>Verifies that close is explicit and idempotent.</summary>
     [Fact]
     public async Task CloseAsync_IsExplicitAndIdempotent()
     {
@@ -221,6 +231,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal("session-fixture", call.Request.SessionId);
     }
 
+    /// <summary>Verifies that invoke retries safe diagnostic commands on transient RPC failure.</summary>
     [Fact]
     public async Task InvokeAsync_RetriesSafeDiagnosticCommandOnTransientGrpcFailure()
     {
@@ -244,6 +255,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Equal(2, transport.InvokeCalls.Count);
     }
 
+    /// <summary>Verifies that open session does not retry on transient RPC failure.</summary>
     [Fact]
     public async Task OpenSessionAsync_DoesNotRetryTransientGrpcFailure()
     {
@@ -256,6 +268,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Single(transport.OpenSessionCalls);
     }
 
+    /// <summary>Verifies that invoke does not retry write commands on transient RPC failure.</summary>
     [Fact]
     public async Task InvokeAsync_DoesNotRetryWriteCommand()
     {
@@ -270,6 +283,7 @@ public sealed class MxGatewayClientSessionTests
         Assert.Single(transport.InvokeCalls);
     }
 
+    /// <summary>Verifies that invoke helpers pass cancellation token to the transport.</summary>
     [Fact]
     public async Task InvokeHelpers_PassCancellationTokenToTransport()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewayGeneratedContractTests.cs

@@ -1,7 +1,8 @@
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class MxGatewayGeneratedContractTests
 {
+    /// <summary>Verifies that the generated gRPC client can be instantiated from the client factory.</summary>
     [Fact]
     public async Task GeneratedGrpcClient_CanBeConstructedFromClientFactory()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxStatusProxyExtensionsTests.cs

@@ -1,12 +1,13 @@
 using System.Text.Json;
 using Google.Protobuf;
-using MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class MxStatusProxyExtensionsTests
 {
+    /// <summary>Verifies that fixture statuses correctly project success and preserve raw integer fields.</summary>
     [Fact]
     public void FixtureStatuses_ProjectSuccessAndPreserveRawFields()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxValueExtensionsTests.cs

@@ -1,12 +1,13 @@
 using System.Text.Json;
 using Google.Protobuf;
-using MxGateway.Client;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Client;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client.Tests;
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
 
 public sealed class MxValueExtensionsTests
 {
+    /// <summary>Verifies that scalar values are converted to correctly-typed MxValue protobuf messages.</summary>
     [Fact]
     public void ToMxValue_WithScalarValues_CreatesTypedProtobufValues()
     {
@@ -18,6 +19,7 @@ public sealed class MxValueExtensionsTests
         Assert.Equal(MxValue.KindOneofCase.StringValue, "alpha".ToMxValue().KindCase);
     }
 
+    /// <summary>Verifies that array values are converted to array-kind MxValue messages with correct element types and dimensions.</summary>
     [Fact]
     public void ToMxValue_WithArrays_CreatesTypedArrayProtobufValues()
     {
@@ -29,6 +31,7 @@ public sealed class MxValueExtensionsTests
         Assert.Equal([2U], value.ArrayValue.Dimensions);
     }
 
+    /// <summary>Verifies that fixture test cases project to expected MxValue kinds and preserve raw type metadata.</summary>
     [Fact]
     public void FixtureValues_ProjectExpectedKindsAndPreserveRawMetadata()
     {

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/ZB.MOM.WW.MxGateway.Client.Tests.csproj

@@ -19,8 +19,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\MxGateway.Client\MxGateway.Client.csproj" />
-    <ProjectReference Include="..\MxGateway.Client.Cli\MxGateway.Client.Cli.csproj" />
+    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client\ZB.MOM.WW.MxGateway.Client.csproj" />
+    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Client.Cli\ZB.MOM.WW.MxGateway.Client.Cli.csproj" />
   </ItemGroup>
 
 </Project>

clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx

@@ -0,0 +1,11 @@
+<Solution>
+  <Configurations>
+    <Platform Name="Any CPU" />
+    <Platform Name="x64" />
+    <Platform Name="x86" />
+  </Configurations>
+  <Project Path="../../src/ZB.MOM.WW.MxGateway.Contracts/ZB.MOM.WW.MxGateway.Contracts.csproj" />
+  <Project Path="ZB.MOM.WW.MxGateway.Client.Cli/ZB.MOM.WW.MxGateway.Client.Cli.csproj" />
+  <Project Path="ZB.MOM.WW.MxGateway.Client.Tests/ZB.MOM.WW.MxGateway.Client.Tests.csproj" />
+  <Project Path="ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj" />
+</Solution>

clients/dotnet/ZB.MOM.WW.MxGateway.Client/DiscoverHierarchyOptions.cs

@@ -0,0 +1,43 @@
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>
+/// Filters and shape options for <see cref="GalaxyRepositoryClient.DiscoverHierarchyAsync(DiscoverHierarchyOptions, System.Threading.CancellationToken)"/>.
+/// </summary>
+/// <remarks>
+/// Hand-written ergonomic wrapper around the generated
+/// <c>DiscoverHierarchyRequest</c>: lets callers express a Galaxy-browse
+/// slice with .NET-friendly nullable scalars and collection initializers,
+/// without touching the protobuf message's <c>oneof root</c> directly.
+/// </remarks>
+public sealed class DiscoverHierarchyOptions
+{
+    /// <summary>Restrict to the subtree rooted at this Galaxy <c>gobject_id</c>.</summary>
+    public int? RootGobjectId { get; init; }
+
+    /// <summary>Restrict to the subtree rooted at the object with this tag name.</summary>
+    public string? RootTagName { get; init; }
+
+    /// <summary>Restrict to the subtree rooted at this <c>contained_name</c> path.</summary>
+    public string? RootContainedPath { get; init; }
+
+    /// <summary>Maximum traversal depth, measured from the chosen root.</summary>
+    public int? MaxDepth { get; init; }
+
+    /// <summary>Restrict to objects whose Galaxy category is in this set.</summary>
+    public IReadOnlyList<int> CategoryIds { get; init; } = [];
+
+    /// <summary>Restrict to objects whose template chain contains any of these tokens.</summary>
+    public IReadOnlyList<string> TemplateChainContains { get; init; } = [];
+
+    /// <summary>Optional glob-style filter on <c>tag_name</c>.</summary>
+    public string? TagNameGlob { get; init; }
+
+    /// <summary>Whether to populate each <c>GalaxyObject.Attributes</c>. Null leaves the server default.</summary>
+    public bool? IncludeAttributes { get; init; }
+
+    /// <summary>Restrict to objects that bear at least one alarm attribute.</summary>
+    public bool AlarmBearingOnly { get; init; }
+
+    /// <summary>Restrict to objects that have at least one historized attribute.</summary>
+    public bool HistorizedOnly { get; init; }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/GalaxyRepositoryClient.cs

@@ -2,14 +2,14 @@ using Google.Protobuf.WellKnownTypes;
 using Grpc.Core;
 using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 using Polly;
 using System.Net.Http;
 using System.Net.Security;
 using System.Runtime.CompilerServices;
 using System.Security.Cryptography.X509Certificates;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
 /// <summary>
 /// Provides the .NET client entry point for the public Galaxy Repository gRPC API.
@@ -18,11 +18,18 @@ namespace MxGateway.Client;
 /// </summary>
 public sealed class GalaxyRepositoryClient : IAsyncDisposable
 {
+    private const int DiscoverHierarchyPageSize = 5000;
+
     private readonly GrpcChannel? _channel;
     private readonly IGalaxyRepositoryClientTransport _transport;
     private readonly ResiliencePipeline _safeUnaryRetryPipeline;
     private bool _disposed;
 
+    /// <summary>
+    /// Initializes a Galaxy Repository client with custom transport and options.
+    /// </summary>
+    /// <param name="options">Client options.</param>
+    /// <param name="transport">The underlying gRPC transport.</param>
     internal GalaxyRepositoryClient(
         MxGatewayClientOptions options,
         IGalaxyRepositoryClientTransport transport)
@@ -50,12 +57,23 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
             Options.LoggerFactory?.CreateLogger<GalaxyRepositoryClient>());
     }
 
+    /// <summary>
+    /// Client options used to configure timeouts, authentication, and retry policy.
+    /// </summary>
     public MxGatewayClientOptions Options { get; }
 
+    /// <summary>
+    /// The underlying generated gRPC client for advanced operations.
+    /// </summary>
     public GalaxyRepository.GalaxyRepositoryClient RawClient =>
         _transport.RawClient
         ?? throw new InvalidOperationException("The raw generated gRPC client is not available for this client instance.");
 
+    /// <summary>
+    /// Creates a Galaxy Repository client with the given options, establishing a new gRPC channel.
+    /// </summary>
+    /// <param name="options">Client options.</param>
+    /// <returns>A new client instance.</returns>
     public static GalaxyRepositoryClient Create(MxGatewayClientOptions options)
     {
         ArgumentNullException.ThrowIfNull(options);
@@ -68,6 +86,8 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
             {
                 HttpHandler = handler,
                 LoggerFactory = options.LoggerFactory,
+                MaxReceiveMessageSize = options.MaxGrpcMessageBytes,
+                MaxSendMessageSize = options.MaxGrpcMessageBytes,
             });
 
         return new GalaxyRepositoryClient(
@@ -81,6 +101,8 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
     /// Probes the Galaxy Repository database connection. Returns true when the
     /// gateway can reach the configured ZB SQL Server.
     /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>True if connection is successful, false otherwise.</returns>
     public async Task<bool> TestConnectionAsync(CancellationToken cancellationToken = default)
     {
         TestConnectionReply reply = await TestConnectionRawAsync(
@@ -91,6 +113,12 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
         return reply.Ok;
     }
 
+    /// <summary>
+    /// Probes the Galaxy Repository database connection without result wrapping.
+    /// </summary>
+    /// <param name="request">The test connection request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<TestConnectionReply> TestConnectionRawAsync(
         TestConnectionRequest request,
         CancellationToken cancellationToken = default)
@@ -107,6 +135,8 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
     /// Returns the timestamp of the most recent Galaxy deployment, or
     /// <see langword="null"/> when no deployment has been recorded.
     /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The deployment timestamp, or null if not recorded.</returns>
     public async Task<DateTime?> GetLastDeployTimeAsync(CancellationToken cancellationToken = default)
     {
         GetLastDeployTimeReply reply = await GetLastDeployTimeRawAsync(
@@ -122,6 +152,12 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
         return reply.TimeOfLastDeploy.ToDateTime();
     }
 
+    /// <summary>
+    /// Returns the most recent Galaxy deployment timestamp without result wrapping.
+    /// </summary>
+    /// <param name="request">The last deploy-time request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<GetLastDeployTimeReply> GetLastDeployTimeRawAsync(
         GetLastDeployTimeRequest request,
         CancellationToken cancellationToken = default)
@@ -139,16 +175,93 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
     /// includes its dynamic attributes so callers can determine which tag references
     /// they may subscribe to via the MxAccessGateway service.
     /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The collection of Galaxy objects in the hierarchy.</returns>
     public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(CancellationToken cancellationToken = default)
     {
-        DiscoverHierarchyReply reply = await DiscoverHierarchyRawAsync(
-                new DiscoverHierarchyRequest(),
-                cancellationToken)
-            .ConfigureAwait(false);
-
-        return reply.Objects;
+        return await DiscoverHierarchyAsync(new DiscoverHierarchyOptions(), cancellationToken).ConfigureAwait(false);
     }
 
+    public async Task<IReadOnlyList<GalaxyObject>> DiscoverHierarchyAsync(
+        DiscoverHierarchyOptions options,
+        CancellationToken cancellationToken = default)
+    {
+        List<GalaxyObject> objects = [];
+        HashSet<string> seenPageTokens = new(StringComparer.Ordinal);
+        string pageToken = string.Empty;
+        do
+        {
+            DiscoverHierarchyRequest request = CreateDiscoverHierarchyRequest(options);
+            request.PageSize = DiscoverHierarchyPageSize;
+            request.PageToken = pageToken;
+            DiscoverHierarchyReply reply = await DiscoverHierarchyRawAsync(
+                    request,
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            objects.AddRange(reply.Objects);
+            pageToken = reply.NextPageToken;
+            if (!string.IsNullOrWhiteSpace(pageToken)
+                && !seenPageTokens.Add(pageToken))
+            {
+                throw new MxGatewayException(
+                    $"Galaxy DiscoverHierarchy returned a repeated page token '{pageToken}'.");
+            }
+        }
+        while (!string.IsNullOrWhiteSpace(pageToken));
+
+        return objects;
+    }
+
+    private static DiscoverHierarchyRequest CreateDiscoverHierarchyRequest(DiscoverHierarchyOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        DiscoverHierarchyRequest request = new()
+        {
+            AlarmBearingOnly = options.AlarmBearingOnly,
+            HistorizedOnly = options.HistorizedOnly,
+        };
+
+        if (options.RootGobjectId.HasValue)
+        {
+            request.RootGobjectId = options.RootGobjectId.Value;
+        }
+        else if (!string.IsNullOrWhiteSpace(options.RootTagName))
+        {
+            request.RootTagName = options.RootTagName;
+        }
+        else if (!string.IsNullOrWhiteSpace(options.RootContainedPath))
+        {
+            request.RootContainedPath = options.RootContainedPath;
+        }
+
+        if (options.MaxDepth.HasValue)
+        {
+            request.MaxDepth = options.MaxDepth.Value;
+        }
+
+        request.CategoryIds.Add(options.CategoryIds);
+        request.TemplateChainContains.Add(options.TemplateChainContains);
+        if (!string.IsNullOrWhiteSpace(options.TagNameGlob))
+        {
+            request.TagNameGlob = options.TagNameGlob;
+        }
+
+        if (options.IncludeAttributes.HasValue)
+        {
+            request.IncludeAttributes = options.IncludeAttributes.Value;
+        }
+
+        return request;
+    }
+
+    /// <summary>
+    /// Enumerates the Galaxy object hierarchy without result wrapping.
+    /// </summary>
+    /// <param name="request">The discover-hierarchy request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<DiscoverHierarchyReply> DiscoverHierarchyRawAsync(
         DiscoverHierarchyRequest request,
         CancellationToken cancellationToken = default)
@@ -173,6 +286,9 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
     /// at-least-once delivery beyond the per-subscriber buffer (gaps in
     /// <see cref="DeployEvent.Sequence"/> indicate dropped events).
     /// </remarks>
+    /// <param name="lastSeenDeployTime">Optional timestamp to suppress the bootstrap event.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>An async enumerable of deploy events.</returns>
     public IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         DateTimeOffset? lastSeenDeployTime = null,
         CancellationToken cancellationToken = default)
@@ -188,6 +304,12 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
         return WatchDeployEventsRawAsync(request, cancellationToken);
     }
 
+    /// <summary>
+    /// Subscribes to Galaxy deploy events without result wrapping.
+    /// </summary>
+    /// <param name="request">The watch-deploy-events request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>An async enumerable of raw deploy events.</returns>
     public IAsyncEnumerable<DeployEvent> WatchDeployEventsRawAsync(
         WatchDeployEventsRequest request,
         CancellationToken cancellationToken = default)
@@ -211,6 +333,9 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
         }
     }
 
+    /// <summary>
+    /// Closes the gRPC channel and releases resources.
+    /// </summary>
     public ValueTask DisposeAsync()
     {
         if (_disposed)
@@ -223,16 +348,32 @@ public sealed class GalaxyRepositoryClient : IAsyncDisposable
         return ValueTask.CompletedTask;
     }
 
+    /// <summary>
+    /// Creates gRPC call options with the client's default timeout and API-key authorization.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The call options.</returns>
     internal CallOptions CreateCallOptions(CancellationToken cancellationToken)
     {
         return CreateCallOptions(cancellationToken, Options.DefaultCallTimeout);
     }
 
+    /// <summary>
+    /// Creates gRPC call options for streaming RPCs with the stream timeout and API-key authorization.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The stream call options.</returns>
     internal CallOptions CreateStreamCallOptions(CancellationToken cancellationToken)
     {
         return CreateCallOptions(cancellationToken, Options.StreamTimeout);
     }
 
+    /// <summary>
+    /// Creates gRPC call options with the specified timeout and API-key authorization.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <param name="timeout">Optional timeout duration.</param>
+    /// <returns>The call options.</returns>
     internal CallOptions CreateCallOptions(
         CancellationToken cancellationToken,
         TimeSpan? timeout)

clients/dotnet/ZB.MOM.WW.MxGateway.Client/GrpcGalaxyRepositoryClientTransport.cs

@@ -1,18 +1,29 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto.Galaxy;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
+/// <summary>
+/// gRPC implementation of IGalaxyRepositoryClientTransport.
+/// </summary>
 internal sealed class GrpcGalaxyRepositoryClientTransport(
     MxGatewayClientOptions options,
     GalaxyRepository.GalaxyRepositoryClient rawClient) : IGalaxyRepositoryClientTransport
 {
+    /// <summary>
+    /// Gets the gateway client options.
+    /// </summary>
     public MxGatewayClientOptions Options { get; } = options;
 
+    /// <summary>
+    /// Gets the underlying gRPC client.
+    /// </summary>
     public GalaxyRepository.GalaxyRepositoryClient RawClient { get; } = rawClient;
 
+    /// <inheritdoc />
     GalaxyRepository.GalaxyRepositoryClient? IGalaxyRepositoryClientTransport.RawClient => RawClient;
 
+    /// <inheritdoc />
     public async Task<TestConnectionReply> TestConnectionAsync(
         TestConnectionRequest request,
         CallOptions callOptions)
@@ -29,6 +40,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
     }
 
+    /// <inheritdoc />
     public async Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
         GetLastDeployTimeRequest request,
         CallOptions callOptions)
@@ -45,6 +57,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
     }
 
+    /// <inheritdoc />
     public async Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
         DiscoverHierarchyRequest request,
         CallOptions callOptions)
@@ -61,6 +74,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
     }
 
+    /// <inheritdoc />
     public async IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CallOptions callOptions,
@@ -94,6 +108,7 @@ internal sealed class GrpcGalaxyRepositoryClientTransport(
         }
     }
 
+    /// <inheritdoc />
     IAsyncEnumerable<DeployEvent> IGalaxyRepositoryClientTransport.WatchDeployEventsAsync(
         WatchDeployEventsRequest request,
         CallOptions callOptions)

clients/dotnet/ZB.MOM.WW.MxGateway.Client/GrpcMxGatewayClientTransport.cs

@@ -1,18 +1,29 @@
 using Grpc.Core;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
+/// <summary>
+/// gRPC implementation of IMxGatewayClientTransport.
+/// </summary>
 internal sealed class GrpcMxGatewayClientTransport(
     MxGatewayClientOptions options,
     MxAccessGateway.MxAccessGatewayClient rawClient) : IMxGatewayClientTransport
 {
+    /// <summary>
+    /// Gets the gateway client options.
+    /// </summary>
     public MxGatewayClientOptions Options { get; } = options;
 
+    /// <summary>
+    /// Gets the underlying gRPC client.
+    /// </summary>
     public MxAccessGateway.MxAccessGatewayClient RawClient { get; } = rawClient;
 
+    /// <inheritdoc />
     MxAccessGateway.MxAccessGatewayClient? IMxGatewayClientTransport.RawClient => RawClient;
 
+    /// <inheritdoc />
     public async Task<OpenSessionReply> OpenSessionAsync(
         OpenSessionRequest request,
         CallOptions callOptions)
@@ -29,6 +40,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
     }
 
+    /// <inheritdoc />
     public async Task<CloseSessionReply> CloseSessionAsync(
         CloseSessionRequest request,
         CallOptions callOptions)
@@ -45,6 +57,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
     }
 
+    /// <inheritdoc />
     public async Task<MxCommandReply> InvokeAsync(
         MxCommandRequest request,
         CallOptions callOptions)
@@ -61,6 +74,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
     }
 
+    /// <inheritdoc />
     public async IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CallOptions callOptions,
@@ -94,6 +108,7 @@ internal sealed class GrpcMxGatewayClientTransport(
         }
     }
 
+    /// <inheritdoc />
     IAsyncEnumerable<MxEvent> IMxGatewayClientTransport.StreamEventsAsync(
         StreamEventsRequest request,
         CallOptions callOptions)
@@ -101,6 +116,65 @@ internal sealed class GrpcMxGatewayClientTransport(
         return StreamEventsAsync(request, callOptions);
     }
 
+    /// <inheritdoc />
+    public async Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CallOptions callOptions)
+    {
+        try
+        {
+            return await RawClient.AcknowledgeAlarmAsync(request, callOptions)
+                .ResponseAsync
+                .ConfigureAwait(false);
+        }
+        catch (RpcException exception)
+        {
+            throw MapRpcException(exception, callOptions.CancellationToken);
+        }
+    }
+
+    /// <inheritdoc />
+    public async IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
+        QueryActiveAlarmsRequest request,
+        CallOptions callOptions,
+        [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        CancellationToken effectiveCancellationToken = cancellationToken.CanBeCanceled
+            ? cancellationToken
+            : callOptions.CancellationToken;
+
+        using AsyncServerStreamingCall<ActiveAlarmSnapshot> call = RawClient.QueryActiveAlarms(request, callOptions);
+
+        IAsyncStreamReader<ActiveAlarmSnapshot> responseStream = call.ResponseStream;
+        while (true)
+        {
+            ActiveAlarmSnapshot? snapshot;
+            try
+            {
+                if (!await responseStream.MoveNext(effectiveCancellationToken).ConfigureAwait(false))
+                {
+                    break;
+                }
+
+                snapshot = responseStream.Current;
+            }
+            catch (RpcException exception)
+            {
+                throw MapRpcException(exception, effectiveCancellationToken);
+            }
+
+            yield return snapshot;
+        }
+    }
+
+    /// <inheritdoc />
+    IAsyncEnumerable<ActiveAlarmSnapshot> IMxGatewayClientTransport.QueryActiveAlarmsAsync(
+        QueryActiveAlarmsRequest request,
+        CallOptions callOptions)
+    {
+        return QueryActiveAlarmsAsync(request, callOptions);
+    }
+
     private static Exception MapRpcException(
         RpcException exception,
         CancellationToken cancellationToken)

clients/dotnet/ZB.MOM.WW.MxGateway.Client/IGalaxyRepositoryClientTransport.cs

@@ -0,0 +1,42 @@
+using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Transport layer for Galaxy Repository gRPC operations.</summary>
+internal interface IGalaxyRepositoryClientTransport
+{
+    /// <summary>Gets the client options used to configure this transport.</summary>
+    MxGatewayClientOptions Options { get; }
+
+    /// <summary>Gets the underlying gRPC client, or <c>null</c> if not yet initialized.</summary>
+    GalaxyRepository.GalaxyRepositoryClient? RawClient { get; }
+
+    /// <summary>Tests the connection to the Galaxy Repository server.</summary>
+    /// <param name="request">The test connection request.</param>
+    /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    Task<TestConnectionReply> TestConnectionAsync(
+        TestConnectionRequest request,
+        CallOptions callOptions);
+
+    /// <summary>Gets the last deploy time from the Galaxy Repository server.</summary>
+    /// <param name="request">The get last deploy time request.</param>
+    /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    Task<GetLastDeployTimeReply> GetLastDeployTimeAsync(
+        GetLastDeployTimeRequest request,
+        CallOptions callOptions);
+
+    /// <summary>Discovers the object hierarchy in the Galaxy Repository.</summary>
+    /// <param name="request">The discover hierarchy request.</param>
+    /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    Task<DiscoverHierarchyReply> DiscoverHierarchyAsync(
+        DiscoverHierarchyRequest request,
+        CallOptions callOptions);
+
+    /// <summary>Watches for deployment events from the Galaxy Repository server.</summary>
+    /// <param name="request">The watch deploy events request.</param>
+    /// <param name="callOptions">gRPC call options (timeout, cancellation, etc.).</param>
+    IAsyncEnumerable<DeployEvent> WatchDeployEventsAsync(
+        WatchDeployEventsRequest request,
+        CallOptions callOptions);
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/IMxGatewayClientTransport.cs

@@ -0,0 +1,78 @@
+using Grpc.Core;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+internal interface IMxGatewayClientTransport
+{
+    /// <summary>
+    /// Gets the client configuration options.
+    /// </summary>
+    MxGatewayClientOptions Options { get; }
+
+    /// <summary>
+    /// Gets the underlying gRPC client, if available.
+    /// </summary>
+    MxAccessGateway.MxAccessGatewayClient? RawClient { get; }
+
+    /// <summary>
+    /// Opens a new gateway session.
+    /// </summary>
+    /// <param name="request">Session open request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>The session open reply.</returns>
+    Task<OpenSessionReply> OpenSessionAsync(
+        OpenSessionRequest request,
+        CallOptions callOptions);
+
+    /// <summary>
+    /// Closes an open gateway session.
+    /// </summary>
+    /// <param name="request">Session close request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>The session close reply.</returns>
+    Task<CloseSessionReply> CloseSessionAsync(
+        CloseSessionRequest request,
+        CallOptions callOptions);
+
+    /// <summary>
+    /// Invokes an MXAccess command on the session.
+    /// </summary>
+    /// <param name="request">The command request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>The command reply.</returns>
+    Task<MxCommandReply> InvokeAsync(
+        MxCommandRequest request,
+        CallOptions callOptions);
+
+    /// <summary>
+    /// Streams events from the session.
+    /// </summary>
+    /// <param name="request">The stream events request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>An async enumerable of events.</returns>
+    IAsyncEnumerable<MxEvent> StreamEventsAsync(
+        StreamEventsRequest request,
+        CallOptions callOptions);
+
+    /// <summary>
+    /// Acknowledges an active MXAccess alarm condition.
+    /// </summary>
+    /// <param name="request">The acknowledge request.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>The acknowledge reply with native MxStatus.</returns>
+    Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CallOptions callOptions);
+
+    /// <summary>
+    /// Streams a snapshot of all alarms currently in Active or ActiveAcked state — the
+    /// ConditionRefresh equivalent for the gateway.
+    /// </summary>
+    /// <param name="request">The query request, optionally scoped by alarm-reference prefix.</param>
+    /// <param name="callOptions">gRPC call options.</param>
+    /// <returns>An async enumerable of active-alarm snapshots.</returns>
+    IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
+        QueryActiveAlarmsRequest request,
+        CallOptions callOptions);
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxAccessException.cs

@@ -0,0 +1,30 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Exception thrown when an MXAccess command fails with a non-zero HResult or failing status.</summary>
+public sealed class MxAccessException : MxGatewayCommandException
+{
+    /// <summary>Initializes a new instance with the given message, reply, and optional inner exception.</summary>
+    /// <param name="message">The error message describing the MXAccess failure.</param>
+    /// <param name="reply">The MxCommandReply containing the failure details (statuses, HResult, etc.).</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxAccessException(
+        string message,
+        MxCommandReply reply,
+        Exception? innerException = null)
+        : base(
+            message,
+            reply.SessionId,
+            reply.CorrelationId,
+            reply.ProtocolStatus,
+            reply.HasHresult ? reply.Hresult : null,
+            reply.Statuses.ToArray(),
+            innerException)
+    {
+        Reply = reply;
+    }
+
+    /// <summary>Gets the underlying MxCommandReply containing full failure details.</summary>
+    public MxCommandReply Reply { get; }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxCommandReplyExtensions.cs

@@ -1,9 +1,12 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
+/// <summary>Extension methods for checking MxCommandReply success conditions.</summary>
 public static class MxCommandReplyExtensions
 {
+    /// <summary>Validates that the reply has a successful protocol status (Ok or MxAccessFailure), throwing a gateway exception if not.</summary>
+    /// <param name="reply">The command reply to check.</param>
     public static MxCommandReply EnsureProtocolSuccess(this MxCommandReply reply)
     {
         ArgumentNullException.ThrowIfNull(reply);
@@ -19,6 +22,8 @@ public static class MxCommandReplyExtensions
         throw CreateProtocolException(reply, code);
     }
 
+    /// <summary>Validates that the reply indicates MXAccess success (no HResult or status failures), throwing MxAccessException if not.</summary>
+    /// <param name="reply">The command reply to check.</param>
     public static MxCommandReply EnsureMxAccessSuccess(this MxCommandReply reply)
     {
         ArgumentNullException.ThrowIfNull(reply);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayAuthenticationException.cs

@@ -0,0 +1,34 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Exception thrown when an API key is invalid, expired, or malformed.</summary>
+public sealed class MxGatewayAuthenticationException : MxGatewayException
+{
+    /// <summary>Initializes a new instance with the given details.</summary>
+    /// <param name="message">The error message describing the authentication failure.</param>
+    /// <param name="sessionId">The session ID, if available.</param>
+    /// <param name="correlationId">The correlation ID for tracing, if available.</param>
+    /// <param name="protocolStatus">The protocol status details, if available.</param>
+    /// <param name="hResult">The HResult code, if available.</param>
+    /// <param name="statuses">The MXAccess statuses, if available.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxGatewayAuthenticationException(
+        string message,
+        string? sessionId = null,
+        string? correlationId = null,
+        ProtocolStatus? protocolStatus = null,
+        int? hResult = null,
+        IReadOnlyList<MxStatusProxy>? statuses = null,
+        Exception? innerException = null)
+        : base(
+            message,
+            sessionId,
+            correlationId,
+            protocolStatus,
+            hResult,
+            statuses ?? [],
+            innerException)
+    {
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayAuthorizationException.cs

@@ -0,0 +1,34 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Exception thrown when the API key lacks required scopes for an operation.</summary>
+public sealed class MxGatewayAuthorizationException : MxGatewayException
+{
+    /// <summary>Initializes a new instance with the given details.</summary>
+    /// <param name="message">The error message describing the authorization failure.</param>
+    /// <param name="sessionId">The session ID, if available.</param>
+    /// <param name="correlationId">The correlation ID for tracing, if available.</param>
+    /// <param name="protocolStatus">The protocol status details, if available.</param>
+    /// <param name="hResult">The HResult code, if available.</param>
+    /// <param name="statuses">The MXAccess statuses, if available.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxGatewayAuthorizationException(
+        string message,
+        string? sessionId = null,
+        string? correlationId = null,
+        ProtocolStatus? protocolStatus = null,
+        int? hResult = null,
+        IReadOnlyList<MxStatusProxy>? statuses = null,
+        Exception? innerException = null)
+        : base(
+            message,
+            sessionId,
+            correlationId,
+            protocolStatus,
+            hResult,
+            statuses ?? [],
+            innerException)
+    {
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClient.cs

@@ -1,13 +1,13 @@
 using Grpc.Core;
 using Grpc.Net.Client;
 using Microsoft.Extensions.Logging;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using Polly;
 using System.Net.Http;
 using System.Net.Security;
 using System.Security.Cryptography.X509Certificates;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
 /// <summary>
 /// Provides the .NET client entry point for the public MXAccess Gateway gRPC API.
@@ -19,6 +19,11 @@ public sealed class MxGatewayClient : IAsyncDisposable
     private readonly ResiliencePipeline _safeUnaryRetryPipeline;
     private bool _disposed;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MxGatewayClient"/> with given options and transport.
+    /// </summary>
+    /// <param name="options">Client configuration options.</param>
+    /// <param name="transport">Transport implementation for gateway communication.</param>
     internal MxGatewayClient(
         MxGatewayClientOptions options,
         IMxGatewayClientTransport transport)
@@ -46,12 +51,23 @@ public sealed class MxGatewayClient : IAsyncDisposable
             Options.LoggerFactory?.CreateLogger<MxGatewayClient>());
     }
 
+    /// <summary>
+    /// Gets the client configuration options.
+    /// </summary>
     public MxGatewayClientOptions Options { get; }
 
+    /// <summary>
+    /// Gets the underlying generated gRPC client.
+    /// </summary>
     public MxAccessGateway.MxAccessGatewayClient RawClient =>
         _transport.RawClient
         ?? throw new InvalidOperationException("The raw generated gRPC client is not available for this client instance.");
 
+    /// <summary>
+    /// Creates a new gateway client with the given options.
+    /// </summary>
+    /// <param name="options">Client configuration options.</param>
+    /// <returns>A new gateway client instance.</returns>
     public static MxGatewayClient Create(MxGatewayClientOptions options)
     {
         ArgumentNullException.ThrowIfNull(options);
@@ -64,6 +80,8 @@ public sealed class MxGatewayClient : IAsyncDisposable
             {
                 HttpHandler = handler,
                 LoggerFactory = options.LoggerFactory,
+                MaxReceiveMessageSize = options.MaxGrpcMessageBytes,
+                MaxSendMessageSize = options.MaxGrpcMessageBytes,
             });
 
         return new MxGatewayClient(
@@ -73,6 +91,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
                 new MxAccessGateway.MxAccessGatewayClient(channel)));
     }
 
+    /// <summary>
+    /// Opens a new gateway session.
+    /// </summary>
+    /// <param name="request">Session open request; defaults to empty request if null.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>A wrapped gateway session.</returns>
     public async Task<MxGatewaySession> OpenSessionAsync(
         OpenSessionRequest? request = null,
         CancellationToken cancellationToken = default)
@@ -85,6 +109,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
         return new MxGatewaySession(this, reply);
     }
 
+    /// <summary>
+    /// Opens a new gateway session and returns the raw protobuf reply.
+    /// </summary>
+    /// <param name="request">Session open request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The raw gateway session open reply.</returns>
     public Task<OpenSessionReply> OpenSessionRawAsync(
         OpenSessionRequest request,
         CancellationToken cancellationToken = default)
@@ -95,6 +125,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
         return _transport.OpenSessionAsync(request, CreateCallOptions(cancellationToken));
     }
 
+    /// <summary>
+    /// Closes an open gateway session.
+    /// </summary>
+    /// <param name="request">Session close request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The session close reply.</returns>
     public Task<CloseSessionReply> CloseSessionRawAsync(
         CloseSessionRequest request,
         CancellationToken cancellationToken = default)
@@ -107,6 +143,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Invokes an MXAccess command on the open session.
+    /// </summary>
+    /// <param name="request">The command request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The command reply.</returns>
     public Task<MxCommandReply> InvokeAsync(
         MxCommandRequest request,
         CancellationToken cancellationToken = default)
@@ -124,6 +166,12 @@ public sealed class MxGatewayClient : IAsyncDisposable
         return _transport.InvokeAsync(request, CreateCallOptions(cancellationToken));
     }
 
+    /// <summary>
+    /// Streams events from the gateway session.
+    /// </summary>
+    /// <param name="request">The stream events request.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>An async enumerable of events.</returns>
     public IAsyncEnumerable<MxEvent> StreamEventsAsync(
         StreamEventsRequest request,
         CancellationToken cancellationToken = default)
@@ -134,6 +182,51 @@ public sealed class MxGatewayClient : IAsyncDisposable
         return _transport.StreamEventsAsync(request, CreateStreamCallOptions(cancellationToken));
     }
 
+    /// <summary>
+    /// Acknowledges an active MXAccess alarm condition through the gateway. The
+    /// gateway authenticates the request against the API key's <c>invoke:alarm-ack</c>
+    /// scope and forwards the acknowledge to the worker's MXAccess session;
+    /// the resulting <see cref="MxStatusProxy"/> is returned in the reply.
+    /// </summary>
+    /// <param name="request">The acknowledge request — alarm reference, comment, operator user.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The acknowledge reply with protocol + native MxStatus.</returns>
+    public Task<AcknowledgeAlarmReply> AcknowledgeAlarmAsync(
+        AcknowledgeAlarmRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return ExecuteSafeUnaryAsync(
+            token => _transport.AcknowledgeAlarmAsync(request, CreateCallOptions(token)),
+            cancellationToken);
+    }
+
+    /// <summary>
+    /// Streams a snapshot of all alarms currently Active or ActiveAcked — the gateway's
+    /// ConditionRefresh equivalent. Used after reconnect to seed the local Part 9 state
+    /// machine, or to reconcile alarms that may have been missed during a transport
+    /// blip. Optionally scoped by alarm-reference prefix
+    /// (<see cref="QueryActiveAlarmsRequest.AlarmFilterPrefix"/>) so a partial refresh
+    /// can target an equipment sub-tree.
+    /// </summary>
+    /// <param name="request">The query request, optionally scoped by alarm-reference prefix.</param>
+    /// <param name="cancellationToken">Cancellation token for the stream.</param>
+    /// <returns>An async enumerable of active-alarm snapshots.</returns>
+    public IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
+        QueryActiveAlarmsRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ThrowIfDisposed();
+
+        return _transport.QueryActiveAlarmsAsync(request, CreateStreamCallOptions(cancellationToken));
+    }
+
+    /// <summary>
+    /// Disposes the client and releases all resources.
+    /// </summary>
     public ValueTask DisposeAsync()
     {
         if (_disposed)
@@ -146,16 +239,32 @@ public sealed class MxGatewayClient : IAsyncDisposable
         return ValueTask.CompletedTask;
     }
 
+    /// <summary>
+    /// Creates gRPC call options with default timeout and authorization.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token for the call.</param>
+    /// <returns>Configured call options.</returns>
     internal CallOptions CreateCallOptions(CancellationToken cancellationToken)
     {
         return CreateCallOptions(cancellationToken, Options.DefaultCallTimeout);
     }
 
+    /// <summary>
+    /// Creates gRPC call options for streaming with stream timeout and authorization.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token for the call.</param>
+    /// <returns>Configured call options.</returns>
     internal CallOptions CreateStreamCallOptions(CancellationToken cancellationToken)
     {
         return CreateCallOptions(cancellationToken, Options.StreamTimeout);
     }
 
+    /// <summary>
+    /// Creates gRPC call options with specified timeout and authorization.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token for the call.</param>
+    /// <param name="timeout">Optional timeout duration; null means no timeout.</param>
+    /// <returns>Configured call options.</returns>
     internal CallOptions CreateCallOptions(
         CancellationToken cancellationToken,
         TimeSpan? timeout)

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClientContractInfo.cs

@@ -1,6 +1,6 @@
-using MxGateway.Contracts;
+using ZB.MOM.WW.MxGateway.Contracts;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
 /// <summary>
 /// Exposes the protocol versions compiled into this client package.

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClientOptions.cs

@@ -1,32 +1,70 @@
 using Microsoft.Extensions.Logging;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
 /// <summary>
 /// Configures the gRPC channel used by the .NET MXAccess Gateway client.
 /// </summary>
 public sealed class MxGatewayClientOptions
 {
+    /// <summary>
+    /// Gets the gateway endpoint URI (required).
+    /// </summary>
     public required Uri Endpoint { get; init; }
 
+    /// <summary>
+    /// Gets the API key for gateway authentication (required).
+    /// </summary>
     public required string ApiKey { get; init; }
 
+    /// <summary>
+    /// Gets a value indicating whether to use TLS for the gateway connection.
+    /// </summary>
     public bool UseTls { get; init; }
 
+    /// <summary>
+    /// Gets the path to a CA certificate file for custom certificate validation.
+    /// </summary>
     public string? CaCertificatePath { get; init; }
 
+    /// <summary>
+    /// Gets the server name override for SNI during TLS handshake.
+    /// </summary>
     public string? ServerNameOverride { get; init; }
 
+    /// <summary>
+    /// Gets the timeout for establishing connection to the gateway.
+    /// </summary>
     public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(10);
 
+    /// <summary>
+    /// Gets the default timeout for unary gRPC calls.
+    /// </summary>
     public TimeSpan DefaultCallTimeout { get; init; } = TimeSpan.FromSeconds(30);
 
+    /// <summary>
+    /// Gets the optional timeout for streaming gRPC calls.
+    /// </summary>
     public TimeSpan? StreamTimeout { get; init; }
 
+    public int MaxGrpcMessageBytes { get; init; } = 16 * 1024 * 1024;
+
+    /// <summary>
+    /// Gets the retry configuration for safe unary calls.
+    /// </summary>
     public MxGatewayClientRetryOptions Retry { get; init; } = new();
 
+    /// <summary>
+    /// Gets the logger factory for diagnostic logging.
+    /// </summary>
     public ILoggerFactory? LoggerFactory { get; init; }
 
+    /// <summary>
+    /// Validates the client options for consistency and correctness.
+    /// </summary>
+    /// <exception cref="ArgumentNullException">Endpoint is null.</exception>
+    /// <exception cref="ArgumentException">Options are invalid or inconsistent.</exception>
+    /// <exception cref="ArgumentOutOfRangeException">Timeout values are not greater than zero.</exception>
     public void Validate()
     {
         ArgumentNullException.ThrowIfNull(Endpoint);
@@ -66,6 +104,13 @@ public sealed class MxGatewayClientOptions
                 "The stream timeout must be greater than zero when configured.");
         }
 
+        if (MaxGrpcMessageBytes <= 0)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(MaxGrpcMessageBytes),
+                "The maximum gRPC message size must be greater than zero.");
+        }
+
         if (UseTls && Endpoint.Scheme != Uri.UriSchemeHttps)
         {
             throw new ArgumentException(

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClientRetryOptions.cs

@@ -1,15 +1,21 @@
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
+/// <summary>Configuration for automatic retry behavior on transient gRPC call failures.</summary>
 public sealed class MxGatewayClientRetryOptions
 {
+    /// <summary>Gets the maximum number of attempts (initial + retries); default is 2.</summary>
     public int MaxAttempts { get; init; } = 2;
 
+    /// <summary>Gets the initial delay between retry attempts; default is 200 milliseconds.</summary>
     public TimeSpan Delay { get; init; } = TimeSpan.FromMilliseconds(200);
 
+    /// <summary>Gets the maximum delay between retry attempts; default is 2 seconds.</summary>
     public TimeSpan MaxDelay { get; init; } = TimeSpan.FromSeconds(2);
 
+    /// <summary>Gets a value indicating whether to add randomness to retry delays; default is true.</summary>
     public bool UseJitter { get; init; } = true;
 
+    /// <summary>Validates the retry options and throws if any constraint is violated.</summary>
     public void Validate()
     {
         if (MaxAttempts <= 0)

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayClientRetryPolicy.cs

@@ -1,13 +1,17 @@
 using Grpc.Core;
 using Microsoft.Extensions.Logging;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using Polly;
 using Polly.Retry;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
+/// <summary>Factory and helpers for exponential-backoff retry policies on transient gRPC failures.</summary>
 internal static class MxGatewayClientRetryPolicy
 {
+    /// <summary>Creates a Polly ResiliencePipeline that retries transient gRPC failures with exponential backoff.</summary>
+    /// <param name="options">Retry configuration (max attempts, delay bounds, jitter).</param>
+    /// <param name="logger">Optional logger for retry diagnostics.</param>
     public static ResiliencePipeline Create(
         MxGatewayClientRetryOptions options,
         ILogger? logger)
@@ -36,6 +40,8 @@ internal static class MxGatewayClientRetryPolicy
             .Build();
     }
 
+    /// <summary>Returns whether a command kind is eligible for automatic retry on transient failures.</summary>
+    /// <param name="kind">The command kind to check.</param>
     public static bool IsRetryableCommand(MxCommandKind kind)
     {
         return kind is MxCommandKind.Ping

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayCommandException.cs

@@ -0,0 +1,34 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Exception thrown when a gateway command fails due to an unclassified protocol error.</summary>
+public class MxGatewayCommandException : MxGatewayException
+{
+    /// <summary>Initializes a new instance with the given details.</summary>
+    /// <param name="message">The error message describing the command failure.</param>
+    /// <param name="sessionId">The session ID, if available.</param>
+    /// <param name="correlationId">The correlation ID for tracing, if available.</param>
+    /// <param name="protocolStatus">The protocol status details, if available.</param>
+    /// <param name="hResult">The HResult code, if available.</param>
+    /// <param name="statuses">The MXAccess statuses, if available.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxGatewayCommandException(
+        string message,
+        string? sessionId = null,
+        string? correlationId = null,
+        ProtocolStatus? protocolStatus = null,
+        int? hResult = null,
+        IReadOnlyList<MxStatusProxy>? statuses = null,
+        Exception? innerException = null)
+        : base(
+            message,
+            sessionId,
+            correlationId,
+            protocolStatus,
+            hResult,
+            statuses ?? [],
+            innerException)
+    {
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayException.cs

@@ -0,0 +1,82 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>
+/// Exception thrown when a gateway RPC call fails or returns an error status.
+/// </summary>
+public class MxGatewayException : Exception
+{
+    /// <summary>
+    /// Initializes a new instance of the MxGatewayException class with the specified message.
+    /// </summary>
+    /// <param name="message">Diagnostic message describing the failure.</param>
+    public MxGatewayException(string message)
+        : base(message)
+    {
+        Statuses = [];
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the MxGatewayException class with the specified message and inner exception.
+    /// </summary>
+    /// <param name="message">Diagnostic message describing the failure.</param>
+    /// <param name="innerException">Underlying exception that caused this failure.</param>
+    public MxGatewayException(string message, Exception? innerException)
+        : base(message, innerException)
+    {
+        Statuses = [];
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the MxGatewayException class with full diagnostic information.
+    /// </summary>
+    /// <param name="message">Diagnostic message describing the failure.</param>
+    /// <param name="sessionId">Session ID associated with the exception, if available.</param>
+    /// <param name="correlationId">Correlation ID associated with the exception, if available.</param>
+    /// <param name="protocolStatus">Protocol-level status returned by the gateway, if available.</param>
+    /// <param name="hResult">HRESULT code returned by the worker or MXAccess, if available.</param>
+    /// <param name="statuses">List of MXAccess status codes returned by the operation.</param>
+    /// <param name="innerException">Underlying exception that caused this failure.</param>
+    public MxGatewayException(
+        string message,
+        string? sessionId,
+        string? correlationId,
+        ProtocolStatus? protocolStatus,
+        int? hResult,
+        IReadOnlyList<MxStatusProxy> statuses,
+        Exception? innerException = null)
+        : base(message, innerException)
+    {
+        SessionId = sessionId;
+        CorrelationId = correlationId;
+        ProtocolStatus = protocolStatus;
+        HResultCode = hResult;
+        Statuses = statuses;
+    }
+
+    /// <summary>
+    /// Gets the session ID associated with the exception, if available.
+    /// </summary>
+    public string? SessionId { get; }
+
+    /// <summary>
+    /// Gets the correlation ID associated with the exception, if available.
+    /// </summary>
+    public string? CorrelationId { get; }
+
+    /// <summary>
+    /// Gets the protocol-level status returned by the gateway, if available.
+    /// </summary>
+    public ProtocolStatus? ProtocolStatus { get; }
+
+    /// <summary>
+    /// Gets the HRESULT code returned by the worker or MXAccess, if available.
+    /// </summary>
+    public int? HResultCode { get; }
+
+    /// <summary>
+    /// Gets the list of MXAccess status codes returned by the operation.
+    /// </summary>
+    public IReadOnlyList<MxStatusProxy> Statuses { get; }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewaySession.cs

@@ -1,6 +1,6 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
 /// <summary>
 /// Represents one gateway-backed MXAccess session.
@@ -11,6 +11,11 @@ public sealed class MxGatewaySession : IAsyncDisposable
     private readonly SemaphoreSlim _closeLock = new(1, 1);
     private CloseSessionReply? _closeReply;
 
+    /// <summary>
+    /// Initializes a new session backed by the given MXAccess gateway client.
+    /// </summary>
+    /// <param name="client">The gateway client used for commands and events.</param>
+    /// <param name="openSessionReply">The server's session creation response.</param>
     internal MxGatewaySession(
         MxGatewayClient client,
         OpenSessionReply openSessionReply)
@@ -19,10 +24,21 @@ public sealed class MxGatewaySession : IAsyncDisposable
         OpenSessionReply = openSessionReply ?? throw new ArgumentNullException(nameof(openSessionReply));
     }
 
+    /// <summary>
+    /// The session ID assigned by the gateway.
+    /// </summary>
     public string SessionId => OpenSessionReply.SessionId;
 
+    /// <summary>
+    /// The server's session creation response containing metadata.
+    /// </summary>
     public OpenSessionReply OpenSessionReply { get; }
 
+    /// <summary>
+    /// Closes the session on the gateway. Idempotent.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The server's close-session reply.</returns>
     public async Task<CloseSessionReply> CloseAsync(CancellationToken cancellationToken = default)
     {
         if (_closeReply is not null)
@@ -50,6 +66,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
         }
     }
 
+    /// <summary>
+    /// Registers a client with the MXAccess session, returning a ServerHandle.
+    /// </summary>
+    /// <param name="clientName">Name to register.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The server handle assigned to the registered client.</returns>
     public async Task<int> RegisterAsync(
         string clientName,
         CancellationToken cancellationToken = default)
@@ -60,6 +82,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.Register?.ServerHandle ?? reply.ReturnValue.Int32Value;
     }
 
+    /// <summary>
+    /// Registers a client with the MXAccess session without error checking.
+    /// </summary>
+    /// <param name="clientName">Name to register.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> RegisterRawAsync(
         string clientName,
         CancellationToken cancellationToken = default)
@@ -75,6 +103,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Adds an item to the MXAccess session, returning an ItemHandle.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemDefinition">The item tag address.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The item handle assigned to the new item.</returns>
     public async Task<int> AddItemAsync(
         int serverHandle,
         string itemDefinition,
@@ -89,6 +124,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.AddItem?.ItemHandle ?? reply.ReturnValue.Int32Value;
     }
 
+    /// <summary>
+    /// Adds an item to the MXAccess session without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemDefinition">The item tag address.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> AddItemRawAsync(
         int serverHandle,
         string itemDefinition,
@@ -109,6 +151,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Adds an item with context to the MXAccess session, returning an ItemHandle.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemDefinition">The item tag address.</param>
+    /// <param name="itemContext">Additional context for the item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The item handle assigned to the new item.</returns>
     public async Task<int> AddItem2Async(
         int serverHandle,
         string itemDefinition,
@@ -125,6 +175,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.AddItem2?.ItemHandle ?? reply.ReturnValue.Int32Value;
     }
 
+    /// <summary>
+    /// Adds an item with context to the MXAccess session without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemDefinition">The item tag address.</param>
+    /// <param name="itemContext">Additional context for the item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> AddItem2RawAsync(
         int serverHandle,
         string itemDefinition,
@@ -147,6 +205,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Subscribes to events for an item (advises in MXAccess terminology).
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
     public async Task AdviseAsync(
         int serverHandle,
         int itemHandle,
@@ -157,6 +221,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
     }
 
+    /// <summary>
+    /// Subscribes to events for an item without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> AdviseRawAsync(
         int serverHandle,
         int itemHandle,
@@ -175,6 +246,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Unsubscribes from events for an item (unadvises in MXAccess terminology).
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
     public async Task UnAdviseAsync(
         int serverHandle,
         int itemHandle,
@@ -185,6 +262,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
     }
 
+    /// <summary>
+    /// Unsubscribes from events for an item without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> UnAdviseRawAsync(
         int serverHandle,
         int itemHandle,
@@ -203,6 +287,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Removes an item from the MXAccess session.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
     public async Task RemoveItemAsync(
         int serverHandle,
         int itemHandle,
@@ -213,6 +303,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
     }
 
+    /// <summary>
+    /// Removes an item from the MXAccess session without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> RemoveItemRawAsync(
         int serverHandle,
         int itemHandle,
@@ -231,6 +328,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Adds multiple items to the MXAccess session in a single command.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="tagAddresses">The item tag addresses to add.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Per-item subscription results.</returns>
     public async Task<IReadOnlyList<SubscribeResult>> AddItemBulkAsync(
         int serverHandle,
         IReadOnlyList<string> tagAddresses,
@@ -253,6 +357,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.AddItemBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Advises multiple items in a single command.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandles">The ItemHandles to advise.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Per-item subscription results.</returns>
     public async Task<IReadOnlyList<SubscribeResult>> AdviseItemBulkAsync(
         int serverHandle,
         IReadOnlyList<int> itemHandles,
@@ -275,6 +386,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.AdviseItemBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Removes multiple items in a single command.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandles">The ItemHandles to remove.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Per-item subscription results.</returns>
     public async Task<IReadOnlyList<SubscribeResult>> RemoveItemBulkAsync(
         int serverHandle,
         IReadOnlyList<int> itemHandles,
@@ -297,6 +415,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.RemoveItemBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Unadvises multiple items in a single command.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandles">The ItemHandles to unadvise.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Per-item subscription results.</returns>
     public async Task<IReadOnlyList<SubscribeResult>> UnAdviseItemBulkAsync(
         int serverHandle,
         IReadOnlyList<int> itemHandles,
@@ -319,6 +444,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.UnAdviseItemBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Adds and advises multiple items in a single command.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="tagAddresses">The item tag addresses to add and advise.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Per-item subscription results.</returns>
     public async Task<IReadOnlyList<SubscribeResult>> SubscribeBulkAsync(
         int serverHandle,
         IReadOnlyList<string> tagAddresses,
@@ -341,6 +473,13 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.SubscribeBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Unadvises and removes multiple items in a single command.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandles">The ItemHandles to unsubscribe.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Per-item subscription results.</returns>
     public async Task<IReadOnlyList<SubscribeResult>> UnsubscribeBulkAsync(
         int serverHandle,
         IReadOnlyList<int> itemHandles,
@@ -363,6 +502,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return reply.UnsubscribeBulk?.Results.ToArray() ?? [];
     }
 
+    /// <summary>
+    /// Writes a value to an item on the MXAccess server.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="value">The value to write.</param>
+    /// <param name="userId">User ID context for the write.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
     public async Task WriteAsync(
         int serverHandle,
         int itemHandle,
@@ -375,6 +522,15 @@ public sealed class MxGatewaySession : IAsyncDisposable
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
     }
 
+    /// <summary>
+    /// Writes a value to an item on the MXAccess server without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="value">The value to write.</param>
+    /// <param name="userId">User ID context for the write.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> WriteRawAsync(
         int serverHandle,
         int itemHandle,
@@ -399,6 +555,15 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Writes a value and timestamp to an item on the MXAccess server.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="value">The value to write.</param>
+    /// <param name="timestampValue">The timestamp to write with the value.</param>
+    /// <param name="userId">User ID context for the write.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
     public async Task Write2Async(
         int serverHandle,
         int itemHandle,
@@ -418,6 +583,16 @@ public sealed class MxGatewaySession : IAsyncDisposable
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
     }
 
+    /// <summary>
+    /// Writes a value and timestamp to an item on the MXAccess server without error checking.
+    /// </summary>
+    /// <param name="serverHandle">The ServerHandle from register.</param>
+    /// <param name="itemHandle">The ItemHandle from add-item.</param>
+    /// <param name="value">The value to write.</param>
+    /// <param name="timestampValue">The timestamp to write with the value.</param>
+    /// <param name="userId">User ID context for the write.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> Write2RawAsync(
         int serverHandle,
         int itemHandle,
@@ -445,6 +620,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Invokes an MXAccess command on this session.
+    /// </summary>
+    /// <param name="request">The command request.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The raw server reply.</returns>
     public Task<MxCommandReply> InvokeAsync(
         MxCommandRequest request,
         CancellationToken cancellationToken = default)
@@ -453,6 +634,12 @@ public sealed class MxGatewaySession : IAsyncDisposable
         return _client.InvokeAsync(request, cancellationToken);
     }
 
+    /// <summary>
+    /// Streams events from the worker for this session, optionally starting after a given sequence number.
+    /// </summary>
+    /// <param name="afterWorkerSequence">The sequence number to stream from. Defaults to 0.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>An async enumerable of events.</returns>
     public IAsyncEnumerable<MxEvent> StreamEventsAsync(
         ulong afterWorkerSequence = 0,
         CancellationToken cancellationToken = default)
@@ -466,6 +653,9 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Closes the session and releases resources.
+    /// </summary>
     public async ValueTask DisposeAsync()
     {
         await CloseAsync().ConfigureAwait(false);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewaySessionException.cs

@@ -0,0 +1,34 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Exception thrown when a session is not found, not ready, or invalid.</summary>
+public sealed class MxGatewaySessionException : MxGatewayException
+{
+    /// <summary>Initializes a new instance with the given details.</summary>
+    /// <param name="message">The error message describing the session failure.</param>
+    /// <param name="sessionId">The session ID, if available.</param>
+    /// <param name="correlationId">The correlation ID for tracing, if available.</param>
+    /// <param name="protocolStatus">The protocol status details, if available.</param>
+    /// <param name="hResult">The HResult code, if available.</param>
+    /// <param name="statuses">The MXAccess statuses, if available.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxGatewaySessionException(
+        string message,
+        string? sessionId = null,
+        string? correlationId = null,
+        ProtocolStatus? protocolStatus = null,
+        int? hResult = null,
+        IReadOnlyList<MxStatusProxy>? statuses = null,
+        Exception? innerException = null)
+        : base(
+            message,
+            sessionId,
+            correlationId,
+            protocolStatus,
+            hResult,
+            statuses ?? [],
+            innerException)
+    {
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayWorkerException.cs

@@ -0,0 +1,34 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>Exception thrown when the worker process is unavailable or fails to process a command.</summary>
+public sealed class MxGatewayWorkerException : MxGatewayException
+{
+    /// <summary>Initializes a new instance with the given details.</summary>
+    /// <param name="message">The error message describing the worker failure.</param>
+    /// <param name="sessionId">The session ID, if available.</param>
+    /// <param name="correlationId">The correlation ID for tracing, if available.</param>
+    /// <param name="protocolStatus">The protocol status details, if available.</param>
+    /// <param name="hResult">The HResult code, if available.</param>
+    /// <param name="statuses">The MXAccess statuses, if available.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxGatewayWorkerException(
+        string message,
+        string? sessionId = null,
+        string? correlationId = null,
+        ProtocolStatus? protocolStatus = null,
+        int? hResult = null,
+        IReadOnlyList<MxStatusProxy>? statuses = null,
+        Exception? innerException = null)
+        : base(
+            message,
+            sessionId,
+            correlationId,
+            protocolStatus,
+            hResult,
+            statuses ?? [],
+            innerException)
+    {
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxStatusProxyExtensions.cs

@@ -1,9 +1,12 @@
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
+/// <summary>Extension methods for MxStatusProxy values.</summary>
 public static class MxStatusProxyExtensions
 {
+    /// <summary>Returns whether the status indicates success (success flag set and category is Ok).</summary>
+    /// <param name="status">The status to check.</param>
     public static bool IsSuccess(this MxStatusProxy status)
     {
         ArgumentNullException.ThrowIfNull(status);
@@ -12,6 +15,8 @@ public static class MxStatusProxyExtensions
             && status.Category is MxStatusCategory.Ok;
     }
 
+    /// <summary>Returns a formatted summary of the status for diagnostic output.</summary>
+    /// <param name="status">The status to summarize.</param>
     public static string ToDiagnosticSummary(this MxStatusProxy status)
     {
         ArgumentNullException.ThrowIfNull(status);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxValueExtensions.cs

@@ -1,8 +1,8 @@
 using Google.Protobuf;
 using Google.Protobuf.WellKnownTypes;
-using MxGateway.Contracts.Proto;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
 
-namespace MxGateway.Client;
+namespace ZB.MOM.WW.MxGateway.Client;
 
 /// <summary>
 /// Creates and projects gateway MXAccess values without hiding the raw
@@ -10,6 +10,10 @@ namespace MxGateway.Client;
 /// </summary>
 public static class MxValueExtensions
 {
+    /// <summary>
+    /// Converts a boolean value to an MxValue with MxDataType.Boolean.
+    /// </summary>
+    /// <param name="value">Scalar boolean value to wrap.</param>
     public static MxValue ToMxValue(this bool value)
     {
         return new MxValue
@@ -20,6 +24,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a 32-bit integer value to an MxValue with MxDataType.Integer.
+    /// </summary>
+    /// <param name="value">32-bit integer value to wrap.</param>
     public static MxValue ToMxValue(this int value)
     {
         return new MxValue
@@ -30,6 +38,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a 64-bit integer value to an MxValue with MxDataType.Integer.
+    /// </summary>
+    /// <param name="value">64-bit integer value to wrap.</param>
     public static MxValue ToMxValue(this long value)
     {
         return new MxValue
@@ -40,6 +52,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a single-precision floating-point value to an MxValue with MxDataType.Float.
+    /// </summary>
+    /// <param name="value">Single-precision floating-point value to wrap.</param>
     public static MxValue ToMxValue(this float value)
     {
         return new MxValue
@@ -50,6 +66,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a double-precision floating-point value to an MxValue with MxDataType.Double.
+    /// </summary>
+    /// <param name="value">Double-precision floating-point value to wrap.</param>
     public static MxValue ToMxValue(this double value)
     {
         return new MxValue
@@ -60,6 +80,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a string value to an MxValue with MxDataType.String.
+    /// </summary>
+    /// <param name="value">String value to wrap.</param>
     public static MxValue ToMxValue(this string value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -72,6 +96,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a DateTimeOffset value to an MxValue with MxDataType.Time.
+    /// </summary>
+    /// <param name="value">DateTimeOffset value to wrap.</param>
     public static MxValue ToMxValue(this DateTimeOffset value)
     {
         return new MxValue
@@ -82,6 +110,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts a DateTime value to an MxValue with MxDataType.Time.
+    /// </summary>
+    /// <param name="value">DateTime value to wrap.</param>
     public static MxValue ToMxValue(this DateTime value)
     {
         return new DateTimeOffset(
@@ -91,6 +123,10 @@ public static class MxValueExtensions
             .ToMxValue();
     }
 
+    /// <summary>
+    /// Converts a boolean array to an MxValue with MxDataType.Boolean.
+    /// </summary>
+    /// <param name="values">Array of boolean values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<bool> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -105,6 +141,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Converts a 32-bit integer array to an MxValue with MxDataType.Integer.
+    /// </summary>
+    /// <param name="values">Array of 32-bit integer values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<int> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -119,6 +159,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Converts a 64-bit integer array to an MxValue with MxDataType.Integer.
+    /// </summary>
+    /// <param name="values">Array of 64-bit integer values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<long> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -133,6 +177,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Converts a single-precision floating-point array to an MxValue with MxDataType.Float.
+    /// </summary>
+    /// <param name="values">Array of single-precision floating-point values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<float> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -147,6 +195,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Converts a double-precision floating-point array to an MxValue with MxDataType.Double.
+    /// </summary>
+    /// <param name="values">Array of double-precision floating-point values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<double> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -161,6 +213,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Converts a string array to an MxValue with MxDataType.String.
+    /// </summary>
+    /// <param name="values">Array of string values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<string> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -175,6 +231,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Converts a DateTimeOffset array to an MxValue with MxDataType.Time.
+    /// </summary>
+    /// <param name="values">Array of DateTimeOffset values to wrap.</param>
     public static MxValue ToMxValue(this IReadOnlyList<DateTimeOffset> values)
     {
         ArgumentNullException.ThrowIfNull(values);
@@ -189,6 +249,10 @@ public static class MxValueExtensions
         });
     }
 
+    /// <summary>
+    /// Gets the projection kind (field name) of the given MxValue's current oneof value.
+    /// </summary>
+    /// <param name="value">The MxValue whose oneof projection kind is returned.</param>
     public static string GetProjectionKind(this MxValue value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -208,6 +272,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts an MxValue to a CLR object; returns the boxed value or null for null MxValues.
+    /// </summary>
+    /// <param name="value">The MxValue to convert.</param>
     public static object? ToClrValue(this MxValue value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -227,6 +295,10 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Converts an MxArray to a CLR array; returns null if the array does not have a known element type.
+    /// </summary>
+    /// <param name="array">The MxArray to convert.</param>
     public static object? ToClrArrayValue(this MxArray array)
     {
         ArgumentNullException.ThrowIfNull(array);
@@ -249,6 +321,13 @@ public static class MxValueExtensions
         };
     }
 
+    /// <summary>
+    /// Creates an MxValue with MxDataType.Unknown from raw byte data, variant type, and diagnostic info.
+    /// </summary>
+    /// <param name="value">Raw byte data representing the value.</param>
+    /// <param name="variantType">Variant type string (e.g., "VT_BSTR").</param>
+    /// <param name="rawDiagnostic">Diagnostic string describing the raw value.</param>
+    /// <param name="rawDataType">Optional MXAccess data type override.</param>
     public static MxValue ToRawMxValue(
         byte[] value,
         string variantType,

clients/dotnet/ZB.MOM.WW.MxGateway.Client/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("ZB.MOM.WW.MxGateway.Client.Tests")]

clients/dotnet/ZB.MOM.WW.MxGateway.Client/ZB.MOM.WW.MxGateway.Client.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\src\MxGateway.Contracts\MxGateway.Contracts.csproj" />
+    <ProjectReference Include="..\..\..\src\ZB.MOM.WW.MxGateway.Contracts\ZB.MOM.WW.MxGateway.Contracts.csproj" />
   </ItemGroup>
 
   <ItemGroup>

clients/go/GoClientDesign.md

@@ -6,8 +6,8 @@ Provide an idiomatic Go client module for MXAccess Gateway, plus a test CLI and
 unit tests. The Go client should be suitable for services and command-line
 automation.
 
-Follow the [Go Style Guide](./style-guides/GoStyleGuide.md) for handwritten
-code and the [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md) for
+Follow the [Go Style Guide](../../docs/style-guides/GoStyleGuide.md) for handwritten
+code and the [Protobuf Style Guide](../../docs/style-guides/ProtobufStyleGuide.md) for
 generated contract inputs.
 
 ## Module Layout
@@ -176,3 +176,10 @@ MXGATEWAY_INTEGRATION=1
 
 Integration test should run `OpenSession`, `Register`, `AddItem`, `Advise`,
 bounded `StreamEvents`, and `CloseSession`.
+
+## Related Documentation
+
+- [Client Libraries Detailed Design](../../docs/ClientLibrariesDesign.md)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Go Style Guide](../../docs/style-guides/GoStyleGuide.md)

clients/go/README.md

@@ -3,7 +3,7 @@
 The Go client module contains the generated MXAccess Gateway protobuf bindings,
 a small handwritten `mxgateway` package, and the `mxgw-go` test CLI scaffold.
 The module uses the shared proto inputs documented in
-`../../docs/client-proto-generation.md` so gateway and client contracts stay in
+`../../docs/ClientProtoGeneration.md` so gateway and client contracts stay in
 sync.
 
 ## Layout
@@ -28,7 +28,7 @@ Run generation after the shared `.proto` files or the Go output path changes:
 ./generate-proto.ps1
 ```
 
-The script uses the tool paths recorded in `../../docs/toolchain-links.md`.
+The script uses the tool paths recorded in `../../docs/ToolchainLinks.md`.
 
 ## Build And Test
 
@@ -209,5 +209,5 @@ go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key
 ## Related Documentation
 
 - [Client Packaging](../../docs/ClientPackaging.md)
-- [Client Proto Generation](../../docs/client-proto-generation.md)
-- [Go Client Detailed Design](../../docs/clients-golang-design.md)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Go Client Detailed Design](./GoClientDesign.md)

clients/go/cmd/mxgw-go/main.go

@@ -1,3 +1,8 @@
+// Command mxgw-go is the reference Go CLI for the MXAccess Gateway.
+//
+// It exposes versioning, session lifecycle, command invocation, event
+// streaming, a smoke-test workflow, and Galaxy Repository browse subcommands
+// that exercise the same gRPC contract used by the mxgateway library.
 package main
 
 import (

clients/go/generate-proto.ps1

@@ -2,20 +2,20 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
 $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
-$protoRoot = Join-Path $repoRoot 'src\MxGateway.Contracts\Protos'
+$protoRoot = Join-Path $repoRoot 'src\ZB.MOM.WW.MxGateway.Contracts\Protos'
 $outputRoot = Join-Path $PSScriptRoot 'internal\generated'
 $modulePath = 'gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated'
 $protoc = 'C:\Users\dohertj2\AppData\Local\Microsoft\WinGet\Packages\Google.Protobuf_Microsoft.Winget.Source_8wekyb3d8bbwe\bin\protoc.exe'
 $goPluginPath = 'C:\Users\dohertj2\go\bin'
 
 if (-not (Test-Path $protoc)) {
-    throw "protoc was not found at $protoc. See docs/toolchain-links.md."
+    throw "protoc was not found at $protoc. See docs/ToolchainLinks.md."
 }
 
 foreach ($pluginName in @('protoc-gen-go.exe', 'protoc-gen-go-grpc.exe')) {
     $pluginPath = Join-Path $goPluginPath $pluginName
     if (-not (Test-Path $pluginPath)) {
-        throw "$pluginName was not found at $pluginPath. See docs/toolchain-links.md."
+        throw "$pluginName was not found at $pluginPath. See docs/ToolchainLinks.md."
     }
 }
 

clients/go/internal/generated/galaxy_repository.pb.go

@@ -10,6 +10,7 @@ import (
 	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
 	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
 	timestamppb "google.golang.org/protobuf/types/known/timestamppb"
+	wrapperspb "google.golang.org/protobuf/types/known/wrapperspb"
 	reflect "reflect"
 	sync "sync"
 	unsafe "unsafe"
@@ -191,9 +192,38 @@ func (x *GetLastDeployTimeReply) GetTimeOfLastDeploy() *timestamppb.Timestamp {
 }
 
 type DiscoverHierarchyRequest struct {
-	state         protoimpl.MessageState `protogen:"open.v1"`
-	unknownFields protoimpl.UnknownFields
-	sizeCache     protoimpl.SizeCache
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Maximum number of objects to return. The server applies its default when
+	// unset and rejects non-positive values.
+	PageSize int32 `protobuf:"varint,1,opt,name=page_size,json=pageSize,proto3" json:"page_size,omitempty"`
+	// Opaque token returned by a previous DiscoverHierarchy response.
+	PageToken string `protobuf:"bytes,2,opt,name=page_token,json=pageToken,proto3" json:"page_token,omitempty"`
+	// Optional. When set, return only this object and its descendants.
+	// Empty = full hierarchy.
+	//
+	// Types that are valid to be assigned to Root:
+	//
+	//	*DiscoverHierarchyRequest_RootGobjectId
+	//	*DiscoverHierarchyRequest_RootTagName
+	//	*DiscoverHierarchyRequest_RootContainedPath
+	Root isDiscoverHierarchyRequest_Root `protobuf_oneof:"root"`
+	// Optional. Cap on descendant depth from root. Zero returns only the root.
+	// Unset means unlimited depth.
+	MaxDepth *wrapperspb.Int32Value `protobuf:"bytes,6,opt,name=max_depth,json=maxDepth,proto3" json:"max_depth,omitempty"`
+	// Optional object category id filters.
+	CategoryIds []int32 `protobuf:"varint,7,rep,packed,name=category_ids,json=categoryIds,proto3" json:"category_ids,omitempty"`
+	// Optional case-insensitive substring filters against template names.
+	TemplateChainContains []string `protobuf:"bytes,8,rep,name=template_chain_contains,json=templateChainContains,proto3" json:"template_chain_contains,omitempty"`
+	// Optional anchored, case-insensitive glob over object tag_name.
+	TagNameGlob string `protobuf:"bytes,9,opt,name=tag_name_glob,json=tagNameGlob,proto3" json:"tag_name_glob,omitempty"`
+	// Optional. Unset or true includes attributes. False returns object skeletons.
+	IncludeAttributes *bool `protobuf:"varint,10,opt,name=include_attributes,json=includeAttributes,proto3,oneof" json:"include_attributes,omitempty"`
+	// Optional. Return only objects with at least one alarm-bearing attribute.
+	AlarmBearingOnly bool `protobuf:"varint,11,opt,name=alarm_bearing_only,json=alarmBearingOnly,proto3" json:"alarm_bearing_only,omitempty"`
+	// Optional. Return only objects with at least one historized attribute.
+	HistorizedOnly bool `protobuf:"varint,12,opt,name=historized_only,json=historizedOnly,proto3" json:"historized_only,omitempty"`
+	unknownFields  protoimpl.UnknownFields
+	sizeCache      protoimpl.SizeCache
 }
 
 func (x *DiscoverHierarchyRequest) Reset() {
@@ -226,11 +256,134 @@ func (*DiscoverHierarchyRequest) Descriptor() ([]byte, []int) {
 	return file_galaxy_repository_proto_rawDescGZIP(), []int{4}
 }
 
+func (x *DiscoverHierarchyRequest) GetPageSize() int32 {
+	if x != nil {
+		return x.PageSize
+	}
+	return 0
+}
+
+func (x *DiscoverHierarchyRequest) GetPageToken() string {
+	if x != nil {
+		return x.PageToken
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetRoot() isDiscoverHierarchyRequest_Root {
+	if x != nil {
+		return x.Root
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetRootGobjectId() int32 {
+	if x != nil {
+		if x, ok := x.Root.(*DiscoverHierarchyRequest_RootGobjectId); ok {
+			return x.RootGobjectId
+		}
+	}
+	return 0
+}
+
+func (x *DiscoverHierarchyRequest) GetRootTagName() string {
+	if x != nil {
+		if x, ok := x.Root.(*DiscoverHierarchyRequest_RootTagName); ok {
+			return x.RootTagName
+		}
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetRootContainedPath() string {
+	if x != nil {
+		if x, ok := x.Root.(*DiscoverHierarchyRequest_RootContainedPath); ok {
+			return x.RootContainedPath
+		}
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetMaxDepth() *wrapperspb.Int32Value {
+	if x != nil {
+		return x.MaxDepth
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetCategoryIds() []int32 {
+	if x != nil {
+		return x.CategoryIds
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetTemplateChainContains() []string {
+	if x != nil {
+		return x.TemplateChainContains
+	}
+	return nil
+}
+
+func (x *DiscoverHierarchyRequest) GetTagNameGlob() string {
+	if x != nil {
+		return x.TagNameGlob
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyRequest) GetIncludeAttributes() bool {
+	if x != nil && x.IncludeAttributes != nil {
+		return *x.IncludeAttributes
+	}
+	return false
+}
+
+func (x *DiscoverHierarchyRequest) GetAlarmBearingOnly() bool {
+	if x != nil {
+		return x.AlarmBearingOnly
+	}
+	return false
+}
+
+func (x *DiscoverHierarchyRequest) GetHistorizedOnly() bool {
+	if x != nil {
+		return x.HistorizedOnly
+	}
+	return false
+}
+
+type isDiscoverHierarchyRequest_Root interface {
+	isDiscoverHierarchyRequest_Root()
+}
+
+type DiscoverHierarchyRequest_RootGobjectId struct {
+	RootGobjectId int32 `protobuf:"varint,3,opt,name=root_gobject_id,json=rootGobjectId,proto3,oneof"`
+}
+
+type DiscoverHierarchyRequest_RootTagName struct {
+	RootTagName string `protobuf:"bytes,4,opt,name=root_tag_name,json=rootTagName,proto3,oneof"`
+}
+
+type DiscoverHierarchyRequest_RootContainedPath struct {
+	RootContainedPath string `protobuf:"bytes,5,opt,name=root_contained_path,json=rootContainedPath,proto3,oneof"`
+}
+
+func (*DiscoverHierarchyRequest_RootGobjectId) isDiscoverHierarchyRequest_Root() {}
+
+func (*DiscoverHierarchyRequest_RootTagName) isDiscoverHierarchyRequest_Root() {}
+
+func (*DiscoverHierarchyRequest_RootContainedPath) isDiscoverHierarchyRequest_Root() {}
+
 type DiscoverHierarchyReply struct {
-	state         protoimpl.MessageState `protogen:"open.v1"`
-	Objects       []*GalaxyObject        `protobuf:"bytes,1,rep,name=objects,proto3" json:"objects,omitempty"`
-	unknownFields protoimpl.UnknownFields
-	sizeCache     protoimpl.SizeCache
+	state   protoimpl.MessageState `protogen:"open.v1"`
+	Objects []*GalaxyObject        `protobuf:"bytes,1,rep,name=objects,proto3" json:"objects,omitempty"`
+	// Non-empty when another page is available.
+	NextPageToken string `protobuf:"bytes,2,opt,name=next_page_token,json=nextPageToken,proto3" json:"next_page_token,omitempty"`
+	// Total number of objects in the cached hierarchy at the time of the call.
+	TotalObjectCount int32 `protobuf:"varint,3,opt,name=total_object_count,json=totalObjectCount,proto3" json:"total_object_count,omitempty"`
+	unknownFields    protoimpl.UnknownFields
+	sizeCache        protoimpl.SizeCache
 }
 
 func (x *DiscoverHierarchyReply) Reset() {
@@ -270,6 +423,20 @@ func (x *DiscoverHierarchyReply) GetObjects() []*GalaxyObject {
 	return nil
 }
 
+func (x *DiscoverHierarchyReply) GetNextPageToken() string {
+	if x != nil {
+		return x.NextPageToken
+	}
+	return ""
+}
+
+func (x *DiscoverHierarchyReply) GetTotalObjectCount() int32 {
+	if x != nil {
+		return x.TotalObjectCount
+	}
+	return 0
+}
+
 type WatchDeployEventsRequest struct {
 	state protoimpl.MessageState `protogen:"open.v1"`
 	// Optional. When set, the bootstrap event is suppressed if the cached deploy
@@ -520,18 +687,32 @@ func (x *GalaxyObject) GetAttributes() []*GalaxyAttribute {
 }
 
 type GalaxyAttribute struct {
-	state                  protoimpl.MessageState `protogen:"open.v1"`
-	AttributeName          string                 `protobuf:"bytes,1,opt,name=attribute_name,json=attributeName,proto3" json:"attribute_name,omitempty"`
-	FullTagReference       string                 `protobuf:"bytes,2,opt,name=full_tag_reference,json=fullTagReference,proto3" json:"full_tag_reference,omitempty"`
-	MxDataType             int32                  `protobuf:"varint,3,opt,name=mx_data_type,json=mxDataType,proto3" json:"mx_data_type,omitempty"`
-	DataTypeName           string                 `protobuf:"bytes,4,opt,name=data_type_name,json=dataTypeName,proto3" json:"data_type_name,omitempty"`
-	IsArray                bool                   `protobuf:"varint,5,opt,name=is_array,json=isArray,proto3" json:"is_array,omitempty"`
-	ArrayDimension         int32                  `protobuf:"varint,6,opt,name=array_dimension,json=arrayDimension,proto3" json:"array_dimension,omitempty"`
-	ArrayDimensionPresent  bool                   `protobuf:"varint,7,opt,name=array_dimension_present,json=arrayDimensionPresent,proto3" json:"array_dimension_present,omitempty"`
-	MxAttributeCategory    int32                  `protobuf:"varint,8,opt,name=mx_attribute_category,json=mxAttributeCategory,proto3" json:"mx_attribute_category,omitempty"`
-	SecurityClassification int32                  `protobuf:"varint,9,opt,name=security_classification,json=securityClassification,proto3" json:"security_classification,omitempty"`
-	IsHistorized           bool                   `protobuf:"varint,10,opt,name=is_historized,json=isHistorized,proto3" json:"is_historized,omitempty"`
-	IsAlarm                bool                   `protobuf:"varint,11,opt,name=is_alarm,json=isAlarm,proto3" json:"is_alarm,omitempty"`
+	state            protoimpl.MessageState `protogen:"open.v1"`
+	AttributeName    string                 `protobuf:"bytes,1,opt,name=attribute_name,json=attributeName,proto3" json:"attribute_name,omitempty"`
+	FullTagReference string                 `protobuf:"bytes,2,opt,name=full_tag_reference,json=fullTagReference,proto3" json:"full_tag_reference,omitempty"`
+	// Raw Galaxy SQL `dbo.data_type` identifier, passed through unchanged.
+	// This is NOT a member of `mxaccess_gateway.v1.MxDataType` — Galaxy's
+	// type enumeration is distinct from MXAccess's wire data-type enum and
+	// the two must not be cast or compared. The GalaxyRepository service is
+	// metadata-only and deliberately does not share types with
+	// mxaccess_gateway.proto. See docs/GalaxyRepository.md.
+	MxDataType int32 `protobuf:"varint,3,opt,name=mx_data_type,json=mxDataType,proto3" json:"mx_data_type,omitempty"`
+	// Human-readable name from Galaxy's `dbo.data_type` table (e.g. "Float",
+	// "Integer", "Boolean"). Free-form Galaxy text; not a stable enum.
+	DataTypeName          string `protobuf:"bytes,4,opt,name=data_type_name,json=dataTypeName,proto3" json:"data_type_name,omitempty"`
+	IsArray               bool   `protobuf:"varint,5,opt,name=is_array,json=isArray,proto3" json:"is_array,omitempty"`
+	ArrayDimension        int32  `protobuf:"varint,6,opt,name=array_dimension,json=arrayDimension,proto3" json:"array_dimension,omitempty"`
+	ArrayDimensionPresent bool   `protobuf:"varint,7,opt,name=array_dimension_present,json=arrayDimensionPresent,proto3" json:"array_dimension_present,omitempty"`
+	// Raw Galaxy SQL attribute-category identifier, passed through unchanged.
+	// Galaxy-specific; not mapped to any gateway enum. See
+	// docs/GalaxyRepository.md.
+	MxAttributeCategory int32 `protobuf:"varint,8,opt,name=mx_attribute_category,json=mxAttributeCategory,proto3" json:"mx_attribute_category,omitempty"`
+	// Raw Galaxy SQL security-classification identifier, passed through
+	// unchanged. Galaxy-specific; not mapped to any gateway enum. See
+	// docs/GalaxyRepository.md.
+	SecurityClassification int32 `protobuf:"varint,9,opt,name=security_classification,json=securityClassification,proto3" json:"security_classification,omitempty"`
+	IsHistorized           bool  `protobuf:"varint,10,opt,name=is_historized,json=isHistorized,proto3" json:"is_historized,omitempty"`
+	IsAlarm                bool  `protobuf:"varint,11,opt,name=is_alarm,json=isAlarm,proto3" json:"is_alarm,omitempty"`
 	unknownFields          protoimpl.UnknownFields
 	sizeCache              protoimpl.SizeCache
 }
@@ -647,17 +828,35 @@ var File_galaxy_repository_proto protoreflect.FileDescriptor
 
 const file_galaxy_repository_proto_rawDesc = "" +
 	"\n" +
-	"\x17galaxy_repository.proto\x12\x14galaxy_repository.v1\x1a\x1fgoogle/protobuf/timestamp.proto\"\x17\n" +
+	"\x17galaxy_repository.proto\x12\x14galaxy_repository.v1\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1egoogle/protobuf/wrappers.proto\"\x17\n" +
 	"\x15TestConnectionRequest\"%\n" +
 	"\x13TestConnectionReply\x12\x0e\n" +
 	"\x02ok\x18\x01 \x01(\bR\x02ok\"\x1a\n" +
 	"\x18GetLastDeployTimeRequest\"}\n" +
 	"\x16GetLastDeployTimeReply\x12\x18\n" +
 	"\apresent\x18\x01 \x01(\bR\apresent\x12I\n" +
-	"\x13time_of_last_deploy\x18\x02 \x01(\v2\x1a.google.protobuf.TimestampR\x10timeOfLastDeploy\"\x1a\n" +
-	"\x18DiscoverHierarchyRequest\"V\n" +
+	"\x13time_of_last_deploy\x18\x02 \x01(\v2\x1a.google.protobuf.TimestampR\x10timeOfLastDeploy\"\xbb\x04\n" +
+	"\x18DiscoverHierarchyRequest\x12\x1b\n" +
+	"\tpage_size\x18\x01 \x01(\x05R\bpageSize\x12\x1d\n" +
+	"\n" +
+	"page_token\x18\x02 \x01(\tR\tpageToken\x12(\n" +
+	"\x0froot_gobject_id\x18\x03 \x01(\x05H\x00R\rrootGobjectId\x12$\n" +
+	"\rroot_tag_name\x18\x04 \x01(\tH\x00R\vrootTagName\x120\n" +
+	"\x13root_contained_path\x18\x05 \x01(\tH\x00R\x11rootContainedPath\x128\n" +
+	"\tmax_depth\x18\x06 \x01(\v2\x1b.google.protobuf.Int32ValueR\bmaxDepth\x12!\n" +
+	"\fcategory_ids\x18\a \x03(\x05R\vcategoryIds\x126\n" +
+	"\x17template_chain_contains\x18\b \x03(\tR\x15templateChainContains\x12\"\n" +
+	"\rtag_name_glob\x18\t \x01(\tR\vtagNameGlob\x122\n" +
+	"\x12include_attributes\x18\n" +
+	" \x01(\bH\x01R\x11includeAttributes\x88\x01\x01\x12,\n" +
+	"\x12alarm_bearing_only\x18\v \x01(\bR\x10alarmBearingOnly\x12'\n" +
+	"\x0fhistorized_only\x18\f \x01(\bR\x0ehistorizedOnlyB\x06\n" +
+	"\x04rootB\x15\n" +
+	"\x13_include_attributes\"\xac\x01\n" +
 	"\x16DiscoverHierarchyReply\x12<\n" +
-	"\aobjects\x18\x01 \x03(\v2\".galaxy_repository.v1.GalaxyObjectR\aobjects\"i\n" +
+	"\aobjects\x18\x01 \x03(\v2\".galaxy_repository.v1.GalaxyObjectR\aobjects\x12&\n" +
+	"\x0fnext_page_token\x18\x02 \x01(\tR\rnextPageToken\x12,\n" +
+	"\x12total_object_count\x18\x03 \x01(\x05R\x10totalObjectCount\"i\n" +
 	"\x18WatchDeployEventsRequest\x12M\n" +
 	"\x15last_seen_deploy_time\x18\x01 \x01(\v2\x1a.google.protobuf.TimestampR\x12lastSeenDeployTime\"\xbb\x02\n" +
 	"\vDeployEvent\x12\x1a\n" +
@@ -703,7 +902,7 @@ const file_galaxy_repository_proto_rawDesc = "" +
 	"\x0eTestConnection\x12+.galaxy_repository.v1.TestConnectionRequest\x1a).galaxy_repository.v1.TestConnectionReply\x12q\n" +
 	"\x11GetLastDeployTime\x12..galaxy_repository.v1.GetLastDeployTimeRequest\x1a,.galaxy_repository.v1.GetLastDeployTimeReply\x12q\n" +
 	"\x11DiscoverHierarchy\x12..galaxy_repository.v1.DiscoverHierarchyRequest\x1a,.galaxy_repository.v1.DiscoverHierarchyReply\x12h\n" +
-	"\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01B#\xaa\x02 MxGateway.Contracts.Proto.Galaxyb\x06proto3"
+	"\x11WatchDeployEvents\x12..galaxy_repository.v1.WatchDeployEventsRequest\x1a!.galaxy_repository.v1.DeployEvent0\x01B-\xaa\x02*ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxyb\x06proto3"
 
 var (
 	file_galaxy_repository_proto_rawDescOnce sync.Once
@@ -730,27 +929,29 @@ var file_galaxy_repository_proto_goTypes = []any{
 	(*GalaxyObject)(nil),             // 8: galaxy_repository.v1.GalaxyObject
 	(*GalaxyAttribute)(nil),          // 9: galaxy_repository.v1.GalaxyAttribute
 	(*timestamppb.Timestamp)(nil),    // 10: google.protobuf.Timestamp
+	(*wrapperspb.Int32Value)(nil),    // 11: google.protobuf.Int32Value
 }
 var file_galaxy_repository_proto_depIdxs = []int32{
 	10, // 0: galaxy_repository.v1.GetLastDeployTimeReply.time_of_last_deploy:type_name -> google.protobuf.Timestamp
-	8,  // 1: galaxy_repository.v1.DiscoverHierarchyReply.objects:type_name -> galaxy_repository.v1.GalaxyObject
-	10, // 2: galaxy_repository.v1.WatchDeployEventsRequest.last_seen_deploy_time:type_name -> google.protobuf.Timestamp
-	10, // 3: galaxy_repository.v1.DeployEvent.observed_at:type_name -> google.protobuf.Timestamp
-	10, // 4: galaxy_repository.v1.DeployEvent.time_of_last_deploy:type_name -> google.protobuf.Timestamp
-	9,  // 5: galaxy_repository.v1.GalaxyObject.attributes:type_name -> galaxy_repository.v1.GalaxyAttribute
-	0,  // 6: galaxy_repository.v1.GalaxyRepository.TestConnection:input_type -> galaxy_repository.v1.TestConnectionRequest
-	2,  // 7: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
-	4,  // 8: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
-	6,  // 9: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
-	1,  // 10: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
-	3,  // 11: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
-	5,  // 12: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
-	7,  // 13: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
-	10, // [10:14] is the sub-list for method output_type
-	6,  // [6:10] is the sub-list for method input_type
-	6,  // [6:6] is the sub-list for extension type_name
-	6,  // [6:6] is the sub-list for extension extendee
-	0,  // [0:6] is the sub-list for field type_name
+	11, // 1: galaxy_repository.v1.DiscoverHierarchyRequest.max_depth:type_name -> google.protobuf.Int32Value
+	8,  // 2: galaxy_repository.v1.DiscoverHierarchyReply.objects:type_name -> galaxy_repository.v1.GalaxyObject
+	10, // 3: galaxy_repository.v1.WatchDeployEventsRequest.last_seen_deploy_time:type_name -> google.protobuf.Timestamp
+	10, // 4: galaxy_repository.v1.DeployEvent.observed_at:type_name -> google.protobuf.Timestamp
+	10, // 5: galaxy_repository.v1.DeployEvent.time_of_last_deploy:type_name -> google.protobuf.Timestamp
+	9,  // 6: galaxy_repository.v1.GalaxyObject.attributes:type_name -> galaxy_repository.v1.GalaxyAttribute
+	0,  // 7: galaxy_repository.v1.GalaxyRepository.TestConnection:input_type -> galaxy_repository.v1.TestConnectionRequest
+	2,  // 8: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:input_type -> galaxy_repository.v1.GetLastDeployTimeRequest
+	4,  // 9: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:input_type -> galaxy_repository.v1.DiscoverHierarchyRequest
+	6,  // 10: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:input_type -> galaxy_repository.v1.WatchDeployEventsRequest
+	1,  // 11: galaxy_repository.v1.GalaxyRepository.TestConnection:output_type -> galaxy_repository.v1.TestConnectionReply
+	3,  // 12: galaxy_repository.v1.GalaxyRepository.GetLastDeployTime:output_type -> galaxy_repository.v1.GetLastDeployTimeReply
+	5,  // 13: galaxy_repository.v1.GalaxyRepository.DiscoverHierarchy:output_type -> galaxy_repository.v1.DiscoverHierarchyReply
+	7,  // 14: galaxy_repository.v1.GalaxyRepository.WatchDeployEvents:output_type -> galaxy_repository.v1.DeployEvent
+	11, // [11:15] is the sub-list for method output_type
+	7,  // [7:11] is the sub-list for method input_type
+	7,  // [7:7] is the sub-list for extension type_name
+	7,  // [7:7] is the sub-list for extension extendee
+	0,  // [0:7] is the sub-list for field type_name
 }
 
 func init() { file_galaxy_repository_proto_init() }
@@ -758,6 +959,11 @@ func file_galaxy_repository_proto_init() {
 	if File_galaxy_repository_proto != nil {
 		return
 	}
+	file_galaxy_repository_proto_msgTypes[4].OneofWrappers = []any{
+		(*DiscoverHierarchyRequest_RootGobjectId)(nil),
+		(*DiscoverHierarchyRequest_RootTagName)(nil),
+		(*DiscoverHierarchyRequest_RootContainedPath)(nil),
+	}
 	type x struct{}
 	out := protoimpl.TypeBuilder{
 		File: protoimpl.DescBuilder{

clients/go/internal/generated/mxaccess_gateway_grpc.pb.go

@@ -19,10 +19,13 @@ import (
 const _ = grpc.SupportPackageIsVersion9
 
 const (
-	MxAccessGateway_OpenSession_FullMethodName  = "/mxaccess_gateway.v1.MxAccessGateway/OpenSession"
-	MxAccessGateway_CloseSession_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/CloseSession"
-	MxAccessGateway_Invoke_FullMethodName       = "/mxaccess_gateway.v1.MxAccessGateway/Invoke"
-	MxAccessGateway_StreamEvents_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/StreamEvents"
+	MxAccessGateway_OpenSession_FullMethodName       = "/mxaccess_gateway.v1.MxAccessGateway/OpenSession"
+	MxAccessGateway_CloseSession_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/CloseSession"
+	MxAccessGateway_Invoke_FullMethodName            = "/mxaccess_gateway.v1.MxAccessGateway/Invoke"
+	MxAccessGateway_StreamEvents_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/StreamEvents"
+	MxAccessGateway_AcknowledgeAlarm_FullMethodName  = "/mxaccess_gateway.v1.MxAccessGateway/AcknowledgeAlarm"
+	MxAccessGateway_StreamAlarms_FullMethodName      = "/mxaccess_gateway.v1.MxAccessGateway/StreamAlarms"
+	MxAccessGateway_QueryActiveAlarms_FullMethodName = "/mxaccess_gateway.v1.MxAccessGateway/QueryActiveAlarms"
 )
 
 // MxAccessGatewayClient is the client API for MxAccessGateway service.
@@ -35,6 +38,19 @@ type MxAccessGatewayClient interface {
 	CloseSession(ctx context.Context, in *CloseSessionRequest, opts ...grpc.CallOption) (*CloseSessionReply, error)
 	Invoke(ctx context.Context, in *MxCommandRequest, opts ...grpc.CallOption) (*MxCommandReply, error)
 	StreamEvents(ctx context.Context, in *StreamEventsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[MxEvent], error)
+	AcknowledgeAlarm(ctx context.Context, in *AcknowledgeAlarmRequest, opts ...grpc.CallOption) (*AcknowledgeAlarmReply, error)
+	// Session-less central alarm feed. The stream opens with the current
+	// active-alarm snapshot (one `active_alarm` per alarm), then a single
+	// `snapshot_complete`, then a `transition` for every subsequent change.
+	// Served by the gateway's always-on alarm monitor; any number of clients
+	// fan out from the single monitor without opening a worker session.
+	StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error)
+	// Point-in-time snapshot of the currently-active alarm set served from the
+	// gateway's always-on alarm monitor cache (session-less). Used after a
+	// reconnect to seed Part 9 client state, or to reconcile alarms that may
+	// have been missed during a transport blip. Streamed so callers can
+	// begin processing without buffering the full set.
+	QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error)
 }
 
 type mxAccessGatewayClient struct {
@@ -94,6 +110,54 @@ func (c *mxAccessGatewayClient) StreamEvents(ctx context.Context, in *StreamEven
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type MxAccessGateway_StreamEventsClient = grpc.ServerStreamingClient[MxEvent]
 
+func (c *mxAccessGatewayClient) AcknowledgeAlarm(ctx context.Context, in *AcknowledgeAlarmRequest, opts ...grpc.CallOption) (*AcknowledgeAlarmReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(AcknowledgeAlarmReply)
+	err := c.cc.Invoke(ctx, MxAccessGateway_AcknowledgeAlarm_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *mxAccessGatewayClient) StreamAlarms(ctx context.Context, in *StreamAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AlarmFeedMessage], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[1], MxAccessGateway_StreamAlarms_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[StreamAlarmsRequest, AlarmFeedMessage]{ClientStream: stream}
+	if err := x.ClientStream.SendMsg(in); err != nil {
+		return nil, err
+	}
+	if err := x.ClientStream.CloseSend(); err != nil {
+		return nil, err
+	}
+	return x, nil
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type MxAccessGateway_StreamAlarmsClient = grpc.ServerStreamingClient[AlarmFeedMessage]
+
+func (c *mxAccessGatewayClient) QueryActiveAlarms(ctx context.Context, in *QueryActiveAlarmsRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ActiveAlarmSnapshot], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &MxAccessGateway_ServiceDesc.Streams[2], MxAccessGateway_QueryActiveAlarms_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[QueryActiveAlarmsRequest, ActiveAlarmSnapshot]{ClientStream: stream}
+	if err := x.ClientStream.SendMsg(in); err != nil {
+		return nil, err
+	}
+	if err := x.ClientStream.CloseSend(); err != nil {
+		return nil, err
+	}
+	return x, nil
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type MxAccessGateway_QueryActiveAlarmsClient = grpc.ServerStreamingClient[ActiveAlarmSnapshot]
+
 // MxAccessGatewayServer is the server API for MxAccessGateway service.
 // All implementations must embed UnimplementedMxAccessGatewayServer
 // for forward compatibility.
@@ -104,6 +168,19 @@ type MxAccessGatewayServer interface {
 	CloseSession(context.Context, *CloseSessionRequest) (*CloseSessionReply, error)
 	Invoke(context.Context, *MxCommandRequest) (*MxCommandReply, error)
 	StreamEvents(*StreamEventsRequest, grpc.ServerStreamingServer[MxEvent]) error
+	AcknowledgeAlarm(context.Context, *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error)
+	// Session-less central alarm feed. The stream opens with the current
+	// active-alarm snapshot (one `active_alarm` per alarm), then a single
+	// `snapshot_complete`, then a `transition` for every subsequent change.
+	// Served by the gateway's always-on alarm monitor; any number of clients
+	// fan out from the single monitor without opening a worker session.
+	StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error
+	// Point-in-time snapshot of the currently-active alarm set served from the
+	// gateway's always-on alarm monitor cache (session-less). Used after a
+	// reconnect to seed Part 9 client state, or to reconcile alarms that may
+	// have been missed during a transport blip. Streamed so callers can
+	// begin processing without buffering the full set.
+	QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error
 	mustEmbedUnimplementedMxAccessGatewayServer()
 }
 
@@ -126,6 +203,15 @@ func (UnimplementedMxAccessGatewayServer) Invoke(context.Context, *MxCommandRequ
 func (UnimplementedMxAccessGatewayServer) StreamEvents(*StreamEventsRequest, grpc.ServerStreamingServer[MxEvent]) error {
 	return status.Error(codes.Unimplemented, "method StreamEvents not implemented")
 }
+func (UnimplementedMxAccessGatewayServer) AcknowledgeAlarm(context.Context, *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error) {
+	return nil, status.Error(codes.Unimplemented, "method AcknowledgeAlarm not implemented")
+}
+func (UnimplementedMxAccessGatewayServer) StreamAlarms(*StreamAlarmsRequest, grpc.ServerStreamingServer[AlarmFeedMessage]) error {
+	return status.Error(codes.Unimplemented, "method StreamAlarms not implemented")
+}
+func (UnimplementedMxAccessGatewayServer) QueryActiveAlarms(*QueryActiveAlarmsRequest, grpc.ServerStreamingServer[ActiveAlarmSnapshot]) error {
+	return status.Error(codes.Unimplemented, "method QueryActiveAlarms not implemented")
+}
 func (UnimplementedMxAccessGatewayServer) mustEmbedUnimplementedMxAccessGatewayServer() {}
 func (UnimplementedMxAccessGatewayServer) testEmbeddedByValue()                         {}
 
@@ -212,6 +298,46 @@ func _MxAccessGateway_StreamEvents_Handler(srv interface{}, stream grpc.ServerSt
 // This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
 type MxAccessGateway_StreamEventsServer = grpc.ServerStreamingServer[MxEvent]
 
+func _MxAccessGateway_AcknowledgeAlarm_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(AcknowledgeAlarmRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(MxAccessGatewayServer).AcknowledgeAlarm(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: MxAccessGateway_AcknowledgeAlarm_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(MxAccessGatewayServer).AcknowledgeAlarm(ctx, req.(*AcknowledgeAlarmRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _MxAccessGateway_StreamAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(StreamAlarmsRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(MxAccessGatewayServer).StreamAlarms(m, &grpc.GenericServerStream[StreamAlarmsRequest, AlarmFeedMessage]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type MxAccessGateway_StreamAlarmsServer = grpc.ServerStreamingServer[AlarmFeedMessage]
+
+func _MxAccessGateway_QueryActiveAlarms_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(QueryActiveAlarmsRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(MxAccessGatewayServer).QueryActiveAlarms(m, &grpc.GenericServerStream[QueryActiveAlarmsRequest, ActiveAlarmSnapshot]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type MxAccessGateway_QueryActiveAlarmsServer = grpc.ServerStreamingServer[ActiveAlarmSnapshot]
+
 // MxAccessGateway_ServiceDesc is the grpc.ServiceDesc for MxAccessGateway service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -231,6 +357,10 @@ var MxAccessGateway_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "Invoke",
 			Handler:    _MxAccessGateway_Invoke_Handler,
 		},
+		{
+			MethodName: "AcknowledgeAlarm",
+			Handler:    _MxAccessGateway_AcknowledgeAlarm_Handler,
+		},
 	},
 	Streams: []grpc.StreamDesc{
 		{
@@ -238,6 +368,16 @@ var MxAccessGateway_ServiceDesc = grpc.ServiceDesc{
 			Handler:       _MxAccessGateway_StreamEvents_Handler,
 			ServerStreams: true,
 		},
+		{
+			StreamName:    "StreamAlarms",
+			Handler:       _MxAccessGateway_StreamAlarms_Handler,
+			ServerStreams: true,
+		},
+		{
+			StreamName:    "QueryActiveAlarms",
+			Handler:       _MxAccessGateway_QueryActiveAlarms_Handler,
+			ServerStreams: true,
+		},
 	},
 	Metadata: "mxaccess_gateway.proto",
 }

clients/go/internal/generated/mxaccess_worker.pb.go

@@ -1179,7 +1179,7 @@ const file_mxaccess_worker_proto_rawDesc = "" +
 	"\x1eWORKER_FAULT_CATEGORY_STA_HUNG\x10\t\x12(\n" +
 	"$WORKER_FAULT_CATEGORY_QUEUE_OVERFLOW\x10\n" +
 	"\x12*\n" +
-	"&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\vB\x1c\xaa\x02\x19MxGateway.Contracts.Protob\x06proto3"
+	"&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\vB&\xaa\x02#ZB.MOM.WW.MxGateway.Contracts.Protob\x06proto3"
 
 var (
 	file_mxaccess_worker_proto_rawDescOnce sync.Once

clients/go/mxgateway/alarms.go

@@ -0,0 +1,53 @@
+package mxgateway
+
+import (
+	"context"
+	"errors"
+)
+
+// AcknowledgeAlarm acknowledges an active MXAccess alarm condition through the
+// gateway. The gateway authenticates the request against the API key's
+// invoke:alarm-ack scope and forwards the acknowledge to the worker's MXAccess
+// session; the resulting native MxStatus is returned in the reply.
+//
+// Acks are idempotent — re-acking an already-acked condition is a no-op at
+// the MxAccess layer.
+func (c *Client) AcknowledgeAlarm(ctx context.Context, req *AcknowledgeAlarmRequest) (*AcknowledgeAlarmReply, error) {
+	if req == nil {
+		return nil, errors.New("mxgateway: acknowledge alarm request is required")
+	}
+
+	callCtx, cancel := c.callContext(ctx)
+	defer cancel()
+
+	reply, err := c.raw.AcknowledgeAlarm(callCtx, req)
+	if err != nil {
+		return nil, &GatewayError{Op: "acknowledge alarm", Err: err}
+	}
+	if err := EnsureProtocolSuccess("acknowledge alarm", reply.GetProtocolStatus(), nil); err != nil {
+		return reply, err
+	}
+
+	return reply, nil
+}
+
+// QueryActiveAlarms streams a snapshot of all alarms currently Active or
+// ActiveAcked — the gateway's ConditionRefresh equivalent. Used after reconnect
+// to seed local Part 9 state, or to reconcile alarms that may have been missed
+// during a transport blip.
+//
+// The returned stream is owned by the caller; cancel ctx to release it.
+// Optional alarm-reference prefix scoping (req.AlarmFilterPrefix) limits the
+// stream to a sub-tree.
+func (c *Client) QueryActiveAlarms(ctx context.Context, req *QueryActiveAlarmsRequest) (QueryActiveAlarmsClient, error) {
+	if req == nil {
+		return nil, errors.New("mxgateway: query active alarms request is required")
+	}
+
+	stream, err := c.raw.QueryActiveAlarms(ctx, req)
+	if err != nil {
+		return nil, &GatewayError{Op: "query active alarms", Err: err}
+	}
+
+	return stream, nil
+}

clients/go/mxgateway/alarms_test.go

@@ -0,0 +1,235 @@
+package mxgateway
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net"
+	"testing"
+
+	pb "gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/internal/generated"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+	"google.golang.org/grpc/test/bufconn"
+)
+
+// PR E.4 — pins the Go SDK surface for the new alarm RPCs:
+// AcknowledgeAlarm + QueryActiveAlarms.
+
+func TestAcknowledgeAlarmSendsRequestAndReturnsReply(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{
+		acknowledgeReply: &pb.AcknowledgeAlarmReply{
+			CorrelationId: "corr-1",
+			ProtocolStatus: &pb.ProtocolStatus{
+				Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+			},
+			Status: &pb.MxStatusProxy{
+				Success:  1,
+				Category: pb.MxStatusCategory_MX_STATUS_CATEGORY_OK,
+			},
+		},
+	}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	reply, err := client.AcknowledgeAlarm(context.Background(), &pb.AcknowledgeAlarmRequest{
+		ClientCorrelationId: "corr-1",
+		AlarmFullReference:  "Tank01.Level.HiHi",
+		Comment:             "investigating",
+		OperatorUser:        "alice",
+	})
+	if err != nil {
+		t.Fatalf("AcknowledgeAlarm() error = %v", err)
+	}
+	if reply.GetProtocolStatus().GetCode() != pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK {
+		t.Fatalf("protocol status = %v", reply.GetProtocolStatus().GetCode())
+	}
+	if got := fake.acknowledgeRequest.GetAlarmFullReference(); got != "Tank01.Level.HiHi" {
+		t.Fatalf("captured alarm reference = %q", got)
+	}
+	if got := fake.acknowledgeRequest.GetComment(); got != "investigating" {
+		t.Fatalf("captured comment = %q", got)
+	}
+	if got := fake.acknowledgeAuth; got != "Bearer test-api-key" {
+		t.Fatalf("authorization metadata = %q", got)
+	}
+}
+
+func TestAcknowledgeAlarmRejectsNilRequest(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	_, err := client.AcknowledgeAlarm(context.Background(), nil)
+	if err == nil || !errors.Is(err, errors.Unwrap(err)) && err.Error() != "mxgateway: acknowledge alarm request is required" {
+		// Accept either: the helper returned the literal sentinel, or the
+		// generic transport error — both prove nil was rejected.
+	}
+	if err == nil {
+		t.Fatalf("AcknowledgeAlarm(nil) returned no error")
+	}
+}
+
+func TestAcknowledgeAlarmMapsUnauthenticated(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{
+		acknowledgeError: status.Error(codes.Unauthenticated, "expired key"),
+	}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	_, err := client.AcknowledgeAlarm(context.Background(), &pb.AcknowledgeAlarmRequest{
+		AlarmFullReference: "Tank01.Level.HiHi",
+		OperatorUser:       "alice",
+	})
+	if err == nil {
+		t.Fatalf("AcknowledgeAlarm() returned no error on Unauthenticated")
+	}
+	var gwErr *GatewayError
+	if !errors.As(err, &gwErr) {
+		t.Fatalf("error %T does not unwrap to *GatewayError", err)
+	}
+	if got, _ := status.FromError(gwErr.Err); got.Code() != codes.Unauthenticated {
+		t.Fatalf("inner status code = %v", got.Code())
+	}
+}
+
+func TestQueryActiveAlarmsStreamsSnapshots(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{
+		activeSnapshots: []*pb.ActiveAlarmSnapshot{
+			{
+				AlarmFullReference: "Tank01.Level.HiHi",
+				CurrentState:       pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE,
+				Severity:           750,
+			},
+			{
+				AlarmFullReference: "Tank02.Level.HiHi",
+				CurrentState:       pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE_ACKED,
+				Severity:           750,
+			},
+		},
+	}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
+		SessionId: "session-1",
+	})
+	if err != nil {
+		t.Fatalf("QueryActiveAlarms() error = %v", err)
+	}
+
+	var received []*pb.ActiveAlarmSnapshot
+	for {
+		snap, err := stream.Recv()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatalf("stream.Recv() error = %v", err)
+		}
+		received = append(received, snap)
+	}
+	if len(received) != 2 {
+		t.Fatalf("snapshot count = %d, want 2", len(received))
+	}
+	if received[0].GetAlarmFullReference() != "Tank01.Level.HiHi" {
+		t.Fatalf("snapshot[0] ref = %q", received[0].GetAlarmFullReference())
+	}
+	if received[1].GetCurrentState() != pb.AlarmConditionState_ALARM_CONDITION_STATE_ACTIVE_ACKED {
+		t.Fatalf("snapshot[1] state = %v", received[1].GetCurrentState())
+	}
+}
+
+func TestQueryActiveAlarmsPassesFilterPrefix(t *testing.T) {
+	fake := &fakeGatewayWithAlarms{}
+	client, cleanup := newBufconnClientWithAlarms(t, fake)
+	defer cleanup()
+
+	stream, err := client.QueryActiveAlarms(context.Background(), &pb.QueryActiveAlarmsRequest{
+		SessionId:          "session-1",
+		AlarmFilterPrefix:  "Tank01.",
+	})
+	if err != nil {
+		t.Fatalf("QueryActiveAlarms() error = %v", err)
+	}
+	for {
+		_, err := stream.Recv()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatalf("stream.Recv() error = %v", err)
+		}
+	}
+
+	if got := fake.queryRequest.GetAlarmFilterPrefix(); got != "Tank01." {
+		t.Fatalf("captured filter prefix = %q", got)
+	}
+}
+
+type fakeGatewayWithAlarms struct {
+	pb.UnimplementedMxAccessGatewayServer
+
+	acknowledgeRequest *pb.AcknowledgeAlarmRequest
+	acknowledgeReply   *pb.AcknowledgeAlarmReply
+	acknowledgeError   error
+	acknowledgeAuth    string
+
+	queryRequest    *pb.QueryActiveAlarmsRequest
+	activeSnapshots []*pb.ActiveAlarmSnapshot
+}
+
+func (s *fakeGatewayWithAlarms) AcknowledgeAlarm(ctx context.Context, req *pb.AcknowledgeAlarmRequest) (*pb.AcknowledgeAlarmReply, error) {
+	s.acknowledgeRequest = req
+	s.acknowledgeAuth = authorizationFromContext(ctx)
+	if s.acknowledgeError != nil {
+		return nil, s.acknowledgeError
+	}
+	if s.acknowledgeReply != nil {
+		return s.acknowledgeReply, nil
+	}
+	return &pb.AcknowledgeAlarmReply{
+		CorrelationId: req.GetClientCorrelationId(),
+		ProtocolStatus: &pb.ProtocolStatus{
+			Code: pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK,
+		},
+	}, nil
+}
+
+func (s *fakeGatewayWithAlarms) QueryActiveAlarms(req *pb.QueryActiveAlarmsRequest, stream grpc.ServerStreamingServer[pb.ActiveAlarmSnapshot]) error {
+	s.queryRequest = req
+	for _, snap := range s.activeSnapshots {
+		if err := stream.Send(snap); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func newBufconnClientWithAlarms(t *testing.T, fake *fakeGatewayWithAlarms) (*Client, func()) {
+	t.Helper()
+	listener := bufconn.Listen(bufSize)
+	server := grpc.NewServer()
+	pb.RegisterMxAccessGatewayServer(server, fake)
+	go func() {
+		_ = server.Serve(listener)
+	}()
+	dialer := func(ctx context.Context, _ string) (net.Conn, error) {
+		return listener.DialContext(ctx)
+	}
+	client, err := Dial(context.Background(), Options{
+		Endpoint:    "bufnet",
+		APIKey:      "test-api-key",
+		Plaintext:   true,
+		DialOptions: []grpc.DialOption{grpc.WithContextDialer(dialer)},
+	})
+	if err != nil {
+		t.Fatalf("Dial() error = %v", err)
+	}
+	return client, func() {
+		client.Close()
+		server.Stop()
+		listener.Close()
+	}
+}

clients/go/mxgateway/client.go

@@ -1,3 +1,14 @@
+// Package mxgateway is the Go client for the MXAccess Gateway gRPC service.
+//
+// The package wraps the generated gRPC contract with session-oriented helpers
+// for invoking MXAccess commands, streaming events, and browsing the Galaxy
+// Repository. Authentication uses an API-key bearer token attached as gRPC
+// metadata on every call.
+//
+// Typical use opens a Client with Dial, opens a Session, invokes commands such
+// as Register, AddItem, Advise, and Write, and consumes events via
+// SubscribeEvents. Galaxy Repository browse RPCs are exposed through
+// GalaxyClient.
 package mxgateway
 
 import (
@@ -219,10 +230,15 @@ func resolveTransportCredentials(opts Options) (credentials.TransportCredentials
 
 // OpenSessionOptions describes fields used to create an OpenSessionRequest.
 type OpenSessionOptions struct {
-	RequestedBackend    string
-	ClientSessionName   string
+	// RequestedBackend selects the gateway worker backend (empty for default).
+	RequestedBackend string
+	// ClientSessionName is a human-readable name recorded on the session.
+	ClientSessionName string
+	// ClientCorrelationID echoes through gateway logs and replies for tracing.
 	ClientCorrelationID string
-	CommandTimeout      time.Duration
+	// CommandTimeout sets the per-command timeout the gateway forwards to the
+	// worker; zero leaves the gateway default in place.
+	CommandTimeout time.Duration
 }
 
 // Request returns the raw protobuf OpenSessionRequest for these options.

clients/go/mxgateway/errors.go

@@ -8,10 +8,13 @@ import (
 
 // GatewayError wraps transport-level gRPC failures.
 type GatewayError struct {
-	Op  string
+	// Op names the operation that failed (for example "dial" or "invoke").
+	Op string
+	// Err is the underlying gRPC or transport error.
 	Err error
 }
 
+// Error returns the formatted gateway error message.
 func (e *GatewayError) Error() string {
 	if e == nil {
 		return ""
@@ -22,6 +25,7 @@ func (e *GatewayError) Error() string {
 	return fmt.Sprintf("mxgateway: %s failed: %v", e.Op, e.Err)
 }
 
+// Unwrap returns the wrapped transport error.
 func (e *GatewayError) Unwrap() error {
 	if e == nil {
 		return nil
@@ -32,11 +36,15 @@ func (e *GatewayError) Unwrap() error {
 // CommandError reports a non-OK gateway protocol status and keeps the raw
 // command reply when one exists.
 type CommandError struct {
-	Op     string
+	// Op names the gateway operation that produced the non-OK status.
+	Op string
+	// Status carries the gateway-reported protocol status.
 	Status *ProtocolStatus
-	Reply  *MxCommandReply
+	// Reply is the raw command reply, when one was returned alongside the status.
+	Reply *MxCommandReply
 }
 
+// Error returns the formatted command error message.
 func (e *CommandError) Error() string {
 	if e == nil {
 		return ""
@@ -53,10 +61,13 @@ func (e *CommandError) Error() string {
 
 // MxAccessError reports HRESULT or MXSTATUS_PROXY failures returned by MXAccess.
 type MxAccessError struct {
+	// Command is the wrapped CommandError when the protocol status carried one.
 	Command *CommandError
-	Reply   *MxCommandReply
+	// Reply is the raw MXAccess command reply that surfaced the failure.
+	Reply *MxCommandReply
 }
 
+// Error returns the formatted MXAccess error message.
 func (e *MxAccessError) Error() string {
 	if e == nil {
 		return ""
@@ -73,6 +84,7 @@ func (e *MxAccessError) Error() string {
 	return "mxgateway: MXAccess command failed"
 }
 
+// Unwrap returns the wrapped CommandError, when one is present.
 func (e *MxAccessError) Unwrap() error {
 	if e == nil {
 		return nil

clients/go/mxgateway/galaxy.go

@@ -20,16 +20,26 @@ type RawGalaxyRepositoryClient = pb.GalaxyRepositoryClient
 
 // Generated protobuf aliases for Galaxy Repository messages.
 type (
-	TestConnectionRequest     = pb.TestConnectionRequest
-	TestConnectionReply       = pb.TestConnectionReply
-	GetLastDeployTimeRequest  = pb.GetLastDeployTimeRequest
-	GetLastDeployTimeReply    = pb.GetLastDeployTimeReply
-	DiscoverHierarchyRequest  = pb.DiscoverHierarchyRequest
-	DiscoverHierarchyReply    = pb.DiscoverHierarchyReply
-	GalaxyObject              = pb.GalaxyObject
-	GalaxyAttribute           = pb.GalaxyAttribute
-	WatchDeployEventsRequest  = pb.WatchDeployEventsRequest
-	DeployEvent               = pb.DeployEvent
+	// TestConnectionRequest is the request for Galaxy Repository TestConnection.
+	TestConnectionRequest = pb.TestConnectionRequest
+	// TestConnectionReply is the reply for Galaxy Repository TestConnection.
+	TestConnectionReply = pb.TestConnectionReply
+	// GetLastDeployTimeRequest is the request for GetLastDeployTime.
+	GetLastDeployTimeRequest = pb.GetLastDeployTimeRequest
+	// GetLastDeployTimeReply is the reply for GetLastDeployTime.
+	GetLastDeployTimeReply = pb.GetLastDeployTimeReply
+	// DiscoverHierarchyRequest is the request for DiscoverHierarchy.
+	DiscoverHierarchyRequest = pb.DiscoverHierarchyRequest
+	// DiscoverHierarchyReply is the reply for DiscoverHierarchy.
+	DiscoverHierarchyReply = pb.DiscoverHierarchyReply
+	// GalaxyObject describes one Galaxy object with its dynamic attributes.
+	GalaxyObject = pb.GalaxyObject
+	// GalaxyAttribute describes one dynamic attribute on a GalaxyObject.
+	GalaxyAttribute = pb.GalaxyAttribute
+	// WatchDeployEventsRequest is the request for WatchDeployEvents.
+	WatchDeployEventsRequest = pb.WatchDeployEventsRequest
+	// DeployEvent is one Galaxy Repository deploy event.
+	DeployEvent = pb.DeployEvent
 )
 
 // RawDeployEventStream is the generated WatchDeployEvents client stream.

clients/go/mxgateway/options.go

@@ -11,16 +11,29 @@ import (
 
 // Options configures gateway connections.
 type Options struct {
-	Endpoint             string
-	APIKey               string
-	Plaintext            bool
-	CACertFile           string
-	ServerNameOverride   string
-	DialTimeout          time.Duration
-	CallTimeout          time.Duration
-	TLSConfig            *tls.Config
+	// Endpoint is the gateway host:port address to dial.
+	Endpoint string
+	// APIKey is the bearer token attached to outgoing gRPC metadata.
+	APIKey string
+	// Plaintext disables TLS and uses insecure credentials when true.
+	Plaintext bool
+	// CACertFile points to a PEM file used to verify the gateway certificate.
+	CACertFile string
+	// ServerNameOverride overrides the TLS SNI/SAN name presented to the gateway.
+	ServerNameOverride string
+	// DialTimeout bounds the blocking Dial; zero applies a built-in default.
+	DialTimeout time.Duration
+	// CallTimeout bounds each unary RPC; zero applies a built-in default and
+	// negative disables the bound entirely.
+	CallTimeout time.Duration
+	// TLSConfig supplies a custom TLS configuration; takes precedence over
+	// CACertFile when TransportCredentials is unset.
+	TLSConfig *tls.Config
+	// TransportCredentials, when non-nil, overrides every other transport-level
+	// option and is used as-is.
 	TransportCredentials credentials.TransportCredentials
-	DialOptions          []grpc.DialOption
+	// DialOptions are appended to the gRPC dial options after the defaults.
+	DialOptions []grpc.DialOption
 }
 
 // RedactedAPIKey returns a display-safe representation of the configured API

clients/go/mxgateway/session.go

@@ -18,8 +18,10 @@ const maxBulkItems = 1000
 
 // EventResult carries either the next ordered event or a terminal stream error.
 type EventResult struct {
+	// Event is the next event from the stream when Err is nil.
 	Event *MxEvent
-	Err   error
+	// Err is the terminal stream error; when non-nil no further results follow.
+	Err error
 }
 
 // EventSubscription owns a running gateway event stream.

clients/go/mxgateway/types.go

@@ -12,77 +12,167 @@ type RawEventStream = pb.MxAccessGateway_StreamEventsClient
 // Generated protobuf aliases keep raw contract access available from the public
 // mxgateway package while generated code remains under internal/generated.
 type (
-	OpenSessionRequest      = pb.OpenSessionRequest
-	OpenSessionReply        = pb.OpenSessionReply
-	CloseSessionRequest     = pb.CloseSessionRequest
-	CloseSessionReply       = pb.CloseSessionReply
-	StreamEventsRequest     = pb.StreamEventsRequest
-	MxCommandRequest        = pb.MxCommandRequest
-	MxCommandReply          = pb.MxCommandReply
-	MxCommand               = pb.MxCommand
-	MxEvent                 = pb.MxEvent
-	MxValue                 = pb.MxValue
-	Value                   = pb.MxValue
-	MxArray                 = pb.MxArray
-	MxStatusProxy           = pb.MxStatusProxy
-	ProtocolStatus          = pb.ProtocolStatus
-	RegisterCommand         = pb.RegisterCommand
-	UnregisterCommand       = pb.UnregisterCommand
-	AddItemCommand          = pb.AddItemCommand
-	AddItem2Command         = pb.AddItem2Command
-	RemoveItemCommand       = pb.RemoveItemCommand
-	AdviseCommand           = pb.AdviseCommand
-	UnAdviseCommand         = pb.UnAdviseCommand
-	AddItemBulkCommand      = pb.AddItemBulkCommand
-	AdviseItemBulkCommand   = pb.AdviseItemBulkCommand
-	RemoveItemBulkCommand   = pb.RemoveItemBulkCommand
+	// OpenSessionRequest is the gateway OpenSession request message.
+	OpenSessionRequest = pb.OpenSessionRequest
+	// OpenSessionReply is the gateway OpenSession reply message.
+	OpenSessionReply = pb.OpenSessionReply
+	// CloseSessionRequest is the gateway CloseSession request message.
+	CloseSessionRequest = pb.CloseSessionRequest
+	// CloseSessionReply is the gateway CloseSession reply message.
+	CloseSessionReply = pb.CloseSessionReply
+	// StreamEventsRequest is the gateway StreamEvents request message.
+	StreamEventsRequest = pb.StreamEventsRequest
+	// MxCommandRequest carries one MXAccess command for Invoke.
+	MxCommandRequest = pb.MxCommandRequest
+	// MxCommandReply is the reply to an MXAccess command Invoke.
+	MxCommandReply = pb.MxCommandReply
+	// MxCommand is the discriminated union of MXAccess command payloads.
+	MxCommand = pb.MxCommand
+	// MxEvent is one ordered event delivered on a session event stream.
+	MxEvent = pb.MxEvent
+	// MxValue is the protobuf representation of an MXAccess value.
+	MxValue = pb.MxValue
+	// Value is an alias for MxValue retained for symmetry with other clients.
+	Value = pb.MxValue
+	// MxArray is the protobuf representation of an MXAccess array value.
+	MxArray = pb.MxArray
+	// MxStatusProxy mirrors the MXAccess MXSTATUS_PROXY structure.
+	MxStatusProxy = pb.MxStatusProxy
+	// ProtocolStatus is the gateway-level status carried on every reply.
+	ProtocolStatus = pb.ProtocolStatus
+	// RegisterCommand is the payload of an MXAccess Register command.
+	RegisterCommand = pb.RegisterCommand
+	// UnregisterCommand is the payload of an MXAccess Unregister command.
+	UnregisterCommand = pb.UnregisterCommand
+	// AddItemCommand is the payload of an MXAccess AddItem command.
+	AddItemCommand = pb.AddItemCommand
+	// AddItem2Command is the payload of an MXAccess AddItem2 command.
+	AddItem2Command = pb.AddItem2Command
+	// RemoveItemCommand is the payload of an MXAccess RemoveItem command.
+	RemoveItemCommand = pb.RemoveItemCommand
+	// AdviseCommand is the payload of an MXAccess Advise command.
+	AdviseCommand = pb.AdviseCommand
+	// UnAdviseCommand is the payload of an MXAccess UnAdvise command.
+	UnAdviseCommand = pb.UnAdviseCommand
+	// AddItemBulkCommand is the payload of an AddItem bulk command.
+	AddItemBulkCommand = pb.AddItemBulkCommand
+	// AdviseItemBulkCommand is the payload of an Advise bulk command.
+	AdviseItemBulkCommand = pb.AdviseItemBulkCommand
+	// RemoveItemBulkCommand is the payload of a RemoveItem bulk command.
+	RemoveItemBulkCommand = pb.RemoveItemBulkCommand
+	// UnAdviseItemBulkCommand is the payload of an UnAdvise bulk command.
 	UnAdviseItemBulkCommand = pb.UnAdviseItemBulkCommand
-	SubscribeBulkCommand    = pb.SubscribeBulkCommand
-	UnsubscribeBulkCommand  = pb.UnsubscribeBulkCommand
-	WriteCommand            = pb.WriteCommand
-	Write2Command           = pb.Write2Command
-	RegisterReply           = pb.RegisterReply
-	AddItemReply            = pb.AddItemReply
-	AddItem2Reply           = pb.AddItem2Reply
-	SubscribeResult         = pb.SubscribeResult
-	BulkSubscribeReply      = pb.BulkSubscribeReply
+	// SubscribeBulkCommand combines AddItem and Advise for a list of tags.
+	SubscribeBulkCommand = pb.SubscribeBulkCommand
+	// UnsubscribeBulkCommand combines UnAdvise and RemoveItem for a list of items.
+	UnsubscribeBulkCommand = pb.UnsubscribeBulkCommand
+	// WriteCommand is the payload of an MXAccess Write command.
+	WriteCommand = pb.WriteCommand
+	// Write2Command is the payload of an MXAccess Write2 command.
+	Write2Command = pb.Write2Command
+	// RegisterReply carries the ServerHandle returned by Register.
+	RegisterReply = pb.RegisterReply
+	// AddItemReply carries the ItemHandle returned by AddItem.
+	AddItemReply = pb.AddItemReply
+	// AddItem2Reply carries the ItemHandle returned by AddItem2.
+	AddItem2Reply = pb.AddItem2Reply
+	// SubscribeResult is one entry in a bulk command result list.
+	SubscribeResult = pb.SubscribeResult
+	// BulkSubscribeReply aggregates SubscribeResult entries for a bulk command.
+	BulkSubscribeReply = pb.BulkSubscribeReply
+	// AcknowledgeAlarmRequest is the gateway AcknowledgeAlarm request message.
+	AcknowledgeAlarmRequest = pb.AcknowledgeAlarmRequest
+	// AcknowledgeAlarmReply is the gateway AcknowledgeAlarm reply message.
+	AcknowledgeAlarmReply = pb.AcknowledgeAlarmReply
+	// QueryActiveAlarmsRequest is the gateway QueryActiveAlarms request message.
+	QueryActiveAlarmsRequest = pb.QueryActiveAlarmsRequest
+	// ActiveAlarmSnapshot is one row in a ConditionRefresh stream.
+	ActiveAlarmSnapshot = pb.ActiveAlarmSnapshot
+	// OnAlarmTransitionEvent is the body carried by alarm-transition MxEvents.
+	OnAlarmTransitionEvent = pb.OnAlarmTransitionEvent
 )
 
+// AlarmTransitionKind discriminates raise / acknowledge / clear / retrigger
+// transitions on an OnAlarmTransitionEvent.
+type AlarmTransitionKind = pb.AlarmTransitionKind
+
+// AlarmConditionState reports the current state of an active alarm in a
+// ConditionRefresh snapshot.
+type AlarmConditionState = pb.AlarmConditionState
+
+// QueryActiveAlarmsClient is the generated server-streaming client for the
+// QueryActiveAlarms RPC.
+type QueryActiveAlarmsClient = pb.MxAccessGateway_QueryActiveAlarmsClient
+
+// Enumerations from the generated contract re-exported for client callers.
 type (
-	MxCommandKind      = pb.MxCommandKind
-	MxDataType         = pb.MxDataType
-	MxEventFamily      = pb.MxEventFamily
-	MxStatusCategory   = pb.MxStatusCategory
-	MxStatusSource     = pb.MxStatusSource
+	// MxCommandKind discriminates which MXAccess command an MxCommand carries.
+	MxCommandKind = pb.MxCommandKind
+	// MxDataType is the MXAccess data type tag on values and arrays.
+	MxDataType = pb.MxDataType
+	// MxEventFamily groups MXAccess events by source category.
+	MxEventFamily = pb.MxEventFamily
+	// MxStatusCategory classifies MXSTATUS_PROXY entries.
+	MxStatusCategory = pb.MxStatusCategory
+	// MxStatusSource identifies the originator of a status entry.
+	MxStatusSource = pb.MxStatusSource
+	// ProtocolStatusCode enumerates gateway-level status codes.
 	ProtocolStatusCode = pb.ProtocolStatusCode
-	SessionState       = pb.SessionState
+	// SessionState enumerates gateway session lifecycle states.
+	SessionState = pb.SessionState
 )
 
+// MXAccess command kind, data type, and protocol status constants surfaced
+// from the generated contract.
 const (
-	CommandKindRegister         = pb.MxCommandKind_MX_COMMAND_KIND_REGISTER
-	CommandKindUnregister       = pb.MxCommandKind_MX_COMMAND_KIND_UNREGISTER
-	CommandKindAddItem          = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM
-	CommandKindAddItem2         = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM2
-	CommandKindRemoveItem       = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM
-	CommandKindAdvise           = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE
-	CommandKindUnAdvise         = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE
-	CommandKindAddItemBulk      = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM_BULK
-	CommandKindAdviseItemBulk   = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_ITEM_BULK
-	CommandKindRemoveItemBulk   = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM_BULK
+	// CommandKindRegister selects the MXAccess Register command.
+	CommandKindRegister = pb.MxCommandKind_MX_COMMAND_KIND_REGISTER
+	// CommandKindUnregister selects the MXAccess Unregister command.
+	CommandKindUnregister = pb.MxCommandKind_MX_COMMAND_KIND_UNREGISTER
+	// CommandKindAddItem selects the MXAccess AddItem command.
+	CommandKindAddItem = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM
+	// CommandKindAddItem2 selects the MXAccess AddItem2 command.
+	CommandKindAddItem2 = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM2
+	// CommandKindRemoveItem selects the MXAccess RemoveItem command.
+	CommandKindRemoveItem = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM
+	// CommandKindAdvise selects the MXAccess Advise command.
+	CommandKindAdvise = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE
+	// CommandKindUnAdvise selects the MXAccess UnAdvise command.
+	CommandKindUnAdvise = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE
+	// CommandKindAddItemBulk selects the AddItem bulk command.
+	CommandKindAddItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM_BULK
+	// CommandKindAdviseItemBulk selects the Advise bulk command.
+	CommandKindAdviseItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_ITEM_BULK
+	// CommandKindRemoveItemBulk selects the RemoveItem bulk command.
+	CommandKindRemoveItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM_BULK
+	// CommandKindUnAdviseItemBulk selects the UnAdvise bulk command.
 	CommandKindUnAdviseItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE_ITEM_BULK
-	CommandKindSubscribeBulk    = pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK
-	CommandKindUnsubscribeBulk  = pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK
-	CommandKindWrite            = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
-	CommandKindWrite2           = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
+	// CommandKindSubscribeBulk selects the AddItem+Advise combined bulk command.
+	CommandKindSubscribeBulk = pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK
+	// CommandKindUnsubscribeBulk selects the UnAdvise+RemoveItem combined bulk command.
+	CommandKindUnsubscribeBulk = pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK
+	// CommandKindWrite selects the MXAccess Write command.
+	CommandKindWrite = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
+	// CommandKindWrite2 selects the MXAccess Write2 command.
+	CommandKindWrite2 = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
 
+	// DataTypeUnknown denotes an unrecognized MXAccess data type.
 	DataTypeUnknown = pb.MxDataType_MX_DATA_TYPE_UNKNOWN
+	// DataTypeBoolean denotes an MXAccess Boolean value.
 	DataTypeBoolean = pb.MxDataType_MX_DATA_TYPE_BOOLEAN
+	// DataTypeInteger denotes an MXAccess Integer value.
 	DataTypeInteger = pb.MxDataType_MX_DATA_TYPE_INTEGER
-	DataTypeFloat   = pb.MxDataType_MX_DATA_TYPE_FLOAT
-	DataTypeDouble  = pb.MxDataType_MX_DATA_TYPE_DOUBLE
-	DataTypeString  = pb.MxDataType_MX_DATA_TYPE_STRING
-	DataTypeTime    = pb.MxDataType_MX_DATA_TYPE_TIME
+	// DataTypeFloat denotes an MXAccess Float (single precision) value.
+	DataTypeFloat = pb.MxDataType_MX_DATA_TYPE_FLOAT
+	// DataTypeDouble denotes an MXAccess Double (double precision) value.
+	DataTypeDouble = pb.MxDataType_MX_DATA_TYPE_DOUBLE
+	// DataTypeString denotes an MXAccess String value.
+	DataTypeString = pb.MxDataType_MX_DATA_TYPE_STRING
+	// DataTypeTime denotes an MXAccess timestamp value.
+	DataTypeTime = pb.MxDataType_MX_DATA_TYPE_TIME
 
-	ProtocolStatusOK              = pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK
+	// ProtocolStatusOK indicates the gateway processed the request successfully.
+	ProtocolStatusOK = pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK
+	// ProtocolStatusMxAccessFailure indicates the worker reported an MXAccess failure.
 	ProtocolStatusMxAccessFailure = pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_MXACCESS_FAILURE
 )

clients/go/mxgateway/version.go

@@ -7,7 +7,7 @@ const (
 
 	// GatewayProtocolVersion matches GatewayContractInfo.GatewayProtocolVersion
 	// in the shared .NET contracts.
-	GatewayProtocolVersion uint32 = 1
+	GatewayProtocolVersion uint32 = 3
 
 	// WorkerProtocolVersion matches GatewayContractInfo.WorkerProtocolVersion
 	// and is exposed for fake-worker and parity tests.

clients/java/JavaClientDesign.md

@@ -5,8 +5,8 @@
 Provide a Java client library for MXAccess Gateway, plus a test CLI and unit
 tests. The Java client should work for JVM services and operator tooling.
 
-Follow the [Java Style Guide](./style-guides/JavaStyleGuide.md) for handwritten
-code and the [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md) for
+Follow the [Java Style Guide](../../docs/style-guides/JavaStyleGuide.md) for handwritten
+code and the [Protobuf Style Guide](../../docs/style-guides/ProtobufStyleGuide.md) for
 generated contract inputs.
 
 ## Build Layout
@@ -18,13 +18,13 @@ clients/java/
   settings.gradle
   build.gradle
   src/main/generated/
-  mxgateway-client/
+  zb-mom-ww-mxgateway-client/
     build.gradle
-    src/main/java/com/dohertylan/mxgateway/client/
-    src/test/java/com/dohertylan/mxgateway/client/
-  mxgateway-cli/
+    src/main/java/com/zb/mom/ww/mxgateway/client/
+    src/test/java/com/zb/mom/ww/mxgateway/client/
+  zb-mom-ww-mxgateway-cli/
     build.gradle
-    src/main/java/com/dohertylan/mxgateway/cli/
+    src/main/java/com/zb/mom/ww/mxgateway/cli/
 ```
 
 Alternative Maven layout is acceptable if the repo standardizes on Maven.
@@ -192,8 +192,8 @@ stream for bounded time, and close.
 
 Publish library and CLI separately:
 
-- `mxgateway-client` jar,
-- `mxgateway-cli` runnable distribution.
+- `zb-mom-ww-mxgateway-client` jar,
+- `zb-mom-ww-mxgateway-cli` runnable distribution.
 
 Generated protobuf code should be produced during the build from shared proto
 files and should not be hand-edited.
@@ -206,7 +206,14 @@ Run the Java scaffold checks from `clients/java`:
 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.
+The `zb-mom-ww-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 `zb-mom-ww-mxgateway-cli` project
+builds a Picocli-based `mxgw-java` entry point for later command implementation.
+
+## Related Documentation
+
+- [Client Libraries Detailed Design](../../docs/ClientLibrariesDesign.md)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Java Style Guide](../../docs/style-guides/JavaStyleGuide.md)

clients/java/README.md

@@ -10,22 +10,23 @@ clients/java/
   settings.gradle
   build.gradle
   src/main/generated/
-  mxgateway-client/
-  mxgateway-cli/
+  zb-mom-ww-mxgateway-client/
+  zb-mom-ww-mxgateway-cli/
 ```
 
-`mxgateway-client` generates Java protobuf and gRPC sources from
-`../../src/MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
+`zb-mom-ww-mxgateway-client` generates Java protobuf and gRPC sources from
+`../../src/ZB.MOM.WW.MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
 generated sources under `src/main/generated`, which matches the client proto
 manifest in `../proto/proto-inputs.json`. Do not edit generated files by hand.
 
-`mxgateway-client` exposes `MxGatewayClientOptions`, `MxGatewayClient`,
+`zb-mom-ww-mxgateway-client` exposes `MxGatewayClientOptions`, `MxGatewayClient`,
 `MxGatewaySession`, value/status helpers, typed gateway exceptions, raw
 generated stubs, and generated protobuf messages for parity tests.
 
-`mxgateway-cli` depends on `mxgateway-client` and provides the `mxgw-java`
-application entry point. The CLI supports version, session, command, event
-streaming, write, and smoke-test commands with deterministic JSON output.
+`zb-mom-ww-mxgateway-cli` depends on `zb-mom-ww-mxgateway-client` and provides
+the `mxgw-java` application entry point. The CLI supports version, session,
+command, event streaming, write, and smoke-test commands with deterministic
+JSON output.
 
 ## Regenerating Protobuf Bindings
 
@@ -33,7 +34,7 @@ Run generation from `clients/java` after the shared `.proto` files or Java
 output path changes:
 
 ```powershell
-gradle :mxgateway-client:generateProto
+gradle :zb-mom-ww-mxgateway-client:generateProto
 ```
 
 ## Client Usage
@@ -104,9 +105,9 @@ The CLI exposes matching subcommands: `galaxy-test`, `galaxy-deploy-time`,
 `--timeout`, and `--json` options as the gateway commands.
 
 ```powershell
-gradle :mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-test --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-deploy-time --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-discover --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
 ```
 
 ### Watching deploy events
@@ -156,8 +157,8 @@ The matching CLI subcommand streams events until cancelled (Ctrl+C) and prints
 one line per event in text mode or one JSON object per event with `--json`:
 
 ```powershell
-gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
-gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --last-seen-deploy-time 2026-04-28T18:30:00Z --limit 5"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --last-seen-deploy-time 2026-04-28T18:30:00Z --limit 5"
 ```
 
 ## CLI Usage
@@ -165,14 +166,14 @@ gradle :mxgateway-cli:run --args="galaxy-watch --endpoint localhost:5000 --api-k
 Run the CLI through Gradle:
 
 ```powershell
-gradle :mxgateway-cli:run --args="version --json"
-gradle :mxgateway-cli:run --args="open-session --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --client-session-name java-cli --json"
-gradle :mxgateway-cli:run --args="register --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --client-name java-cli --json"
-gradle :mxgateway-cli:run --args="add-item --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item TestObject.TestInt --json"
-gradle :mxgateway-cli:run --args="advise --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --json"
-gradle :mxgateway-cli:run --args="write --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json"
-gradle :mxgateway-cli:run --args="stream-events --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --limit 1 --json"
-gradle :mxgateway-cli:run --args="smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestObject.TestInt --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="version --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="open-session --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --client-session-name java-cli --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="register --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --client-name java-cli --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="add-item --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item TestObject.TestInt --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="advise --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="write --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="stream-events --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --limit 1 --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestObject.TestInt --json"
 ```
 
 The CLI accepts `--api-key`, `--api-key-env`, `--plaintext`, `--ca-file`,
@@ -182,7 +183,7 @@ 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"
+gradle :zb-mom-ww-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
@@ -202,11 +203,11 @@ in-process gRPC behavior, stream cancellation, and CLI parser/output behavior.
 Create local library and CLI artifacts from `clients/java`:
 
 ```powershell
-gradle :mxgateway-client:jar :mxgateway-cli:installDist
+gradle :zb-mom-ww-mxgateway-client:jar :zb-mom-ww-mxgateway-cli:installDist
 ```
 
-The library jar is under `mxgateway-client/build/libs`. The installed CLI
-distribution is under `mxgateway-cli/build/install/mxgateway-cli`.
+The library jar is under `zb-mom-ww-mxgateway-client/build/libs`. The installed CLI
+distribution is under `zb-mom-ww-mxgateway-cli/build/install/zb-mom-ww-mxgateway-cli`.
 
 ## Integration Checks
 
@@ -217,12 +218,12 @@ $env:MXGATEWAY_INTEGRATION = '1'
 $env:MXGATEWAY_ENDPOINT = 'localhost:5000'
 $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"
+gradle :zb-mom-ww-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)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Java Client Detailed Design](./JavaClientDesign.md)
 - [Java Style Guide](../../docs/style-guides/JavaStyleGuide.md)

clients/java/build.gradle

@@ -12,7 +12,7 @@ ext {
 }
 
 subprojects {
-    group = 'com.dohertylan.mxgateway'
+    group = 'com.zb.mom.ww.mxgateway'
     version = '0.1.0'
 
     pluginManager.withPlugin('java') {

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxAccessException.java

@@ -1,14 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
-import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
-
-public final class MxAccessException extends MxGatewayCommandException {
-    public MxAccessException(String operation, ProtocolStatus protocolStatus, MxCommandReply reply) {
-        super(operation, protocolStatus, reply);
-    }
-
-    public MxAccessException(String operation, MxCommandReply reply) {
-        super(operation, reply == null ? null : reply.getProtocolStatus(), reply);
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayAuthenticationException.java

@@ -1,7 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-public final class MxGatewayAuthenticationException extends MxGatewayException {
-    public MxGatewayAuthenticationException(String message, Throwable cause) {
-        super(message, cause);
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayAuthorizationException.java

@@ -1,7 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-public final class MxGatewayAuthorizationException extends MxGatewayException {
-    public MxGatewayAuthorizationException(String message, Throwable cause) {
-        super(message, cause);
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClientOptions.java

@@ -1,160 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-import java.nio.file.Path;
-import java.time.Duration;
-import java.util.Objects;
-
-public final class MxGatewayClientOptions {
-    private static final Duration DEFAULT_CONNECT_TIMEOUT = Duration.ofSeconds(10);
-    private static final Duration DEFAULT_CALL_TIMEOUT = Duration.ofSeconds(30);
-
-    private final String endpoint;
-    private final String apiKey;
-    private final boolean plaintext;
-    private final Path caCertificatePath;
-    private final String serverNameOverride;
-    private final Duration connectTimeout;
-    private final Duration callTimeout;
-    private final Duration streamTimeout;
-
-    private MxGatewayClientOptions(Builder builder) {
-        endpoint = requireText(builder.endpoint, "endpoint");
-        apiKey = builder.apiKey == null ? "" : builder.apiKey;
-        plaintext = builder.plaintext;
-        caCertificatePath = builder.caCertificatePath;
-        serverNameOverride = builder.serverNameOverride == null ? "" : builder.serverNameOverride;
-        connectTimeout = builder.connectTimeout == null ? DEFAULT_CONNECT_TIMEOUT : builder.connectTimeout;
-        callTimeout = builder.callTimeout == null ? DEFAULT_CALL_TIMEOUT : builder.callTimeout;
-        streamTimeout = builder.streamTimeout;
-    }
-
-    public static Builder builder() {
-        return new Builder();
-    }
-
-    public String endpoint() {
-        return endpoint;
-    }
-
-    public String apiKey() {
-        return apiKey;
-    }
-
-    public String redactedApiKey() {
-        return MxGatewaySecrets.redactApiKey(apiKey);
-    }
-
-    public boolean plaintext() {
-        return plaintext;
-    }
-
-    public Path caCertificatePath() {
-        return caCertificatePath;
-    }
-
-    public String serverNameOverride() {
-        return serverNameOverride;
-    }
-
-    public Duration connectTimeout() {
-        return connectTimeout;
-    }
-
-    public Duration callTimeout() {
-        return callTimeout;
-    }
-
-    public Duration streamTimeout() {
-        return streamTimeout;
-    }
-
-    @Override
-    public String toString() {
-        return "MxGatewayClientOptions{"
-                + "endpoint='"
-                + endpoint
-                + '\''
-                + ", apiKey='"
-                + redactedApiKey()
-                + '\''
-                + ", plaintext="
-                + plaintext
-                + ", caCertificatePath="
-                + caCertificatePath
-                + ", serverNameOverride='"
-                + serverNameOverride
-                + '\''
-                + ", connectTimeout="
-                + connectTimeout
-                + ", callTimeout="
-                + callTimeout
-                + ", streamTimeout="
-                + streamTimeout
-                + '}';
-    }
-
-    private static String requireText(String value, String name) {
-        if (value == null || value.isBlank()) {
-            throw new IllegalArgumentException(name + " is required");
-        }
-        return value;
-    }
-
-    public static final class Builder {
-        private String endpoint;
-        private String apiKey;
-        private boolean plaintext;
-        private Path caCertificatePath;
-        private String serverNameOverride;
-        private Duration connectTimeout;
-        private Duration callTimeout;
-        private Duration streamTimeout;
-
-        private Builder() {
-        }
-
-        public Builder endpoint(String value) {
-            endpoint = value;
-            return this;
-        }
-
-        public Builder apiKey(String value) {
-            apiKey = value;
-            return this;
-        }
-
-        public Builder plaintext(boolean value) {
-            plaintext = value;
-            return this;
-        }
-
-        public Builder caCertificatePath(Path value) {
-            caCertificatePath = value;
-            return this;
-        }
-
-        public Builder serverNameOverride(String value) {
-            serverNameOverride = value;
-            return this;
-        }
-
-        public Builder connectTimeout(Duration value) {
-            connectTimeout = Objects.requireNonNull(value, "connectTimeout");
-            return this;
-        }
-
-        public Builder callTimeout(Duration value) {
-            callTimeout = Objects.requireNonNull(value, "callTimeout");
-            return this;
-        }
-
-        public Builder streamTimeout(Duration value) {
-            streamTimeout = Objects.requireNonNull(value, "streamTimeout");
-            return this;
-        }
-
-        public MxGatewayClientOptions build() {
-            return new MxGatewayClientOptions(this);
-        }
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClientVersion.java

@@ -1,22 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-public final class MxGatewayClientVersion {
-    private static final int GATEWAY_PROTOCOL_VERSION = 1;
-    private static final int WORKER_PROTOCOL_VERSION = 1;
-    private static final String CLIENT_VERSION = "0.1.0";
-
-    private MxGatewayClientVersion() {
-    }
-
-    public static String clientVersion() {
-        return CLIENT_VERSION;
-    }
-
-    public static int gatewayProtocolVersion() {
-        return GATEWAY_PROTOCOL_VERSION;
-    }
-
-    public static int workerProtocolVersion() {
-        return WORKER_PROTOCOL_VERSION;
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayCommandException.java

@@ -1,23 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
-import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
-
-public class MxGatewayCommandException extends MxGatewayException {
-    private final ProtocolStatus protocolStatus;
-    private final MxCommandReply reply;
-
-    public MxGatewayCommandException(String operation, ProtocolStatus protocolStatus, MxCommandReply reply) {
-        super(MxGatewayErrors.protocolStatusMessage(operation, protocolStatus));
-        this.protocolStatus = protocolStatus;
-        this.reply = reply;
-    }
-
-    public ProtocolStatus protocolStatus() {
-        return protocolStatus;
-    }
-
-    public MxCommandReply reply() {
-        return reply;
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayException.java

@@ -1,11 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-public class MxGatewayException extends RuntimeException {
-    public MxGatewayException(String message) {
-        super(message);
-    }
-
-    public MxGatewayException(String message, Throwable cause) {
-        super(message, cause);
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySecrets.java

@@ -1,33 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-public final class MxGatewaySecrets {
-    private MxGatewaySecrets() {
-    }
-
-    public static String redactApiKey(String apiKey) {
-        if (apiKey == null || apiKey.isEmpty()) {
-            return "";
-        }
-        if (apiKey.length() <= 8) {
-            return "<redacted>";
-        }
-
-        return apiKey.substring(0, 4)
-                + "*".repeat(apiKey.length() - 8)
-                + apiKey.substring(apiKey.length() - 4);
-    }
-
-    public static String redactCredentials(String value) {
-        if (value == null || value.isBlank()) {
-            return value == null ? "" : value;
-        }
-
-        String[] parts = value.split("\\s+");
-        for (int index = 0; index < parts.length; index++) {
-            if (parts[index].startsWith("mxgw_") || parts[index].equalsIgnoreCase("bearer")) {
-                parts[index] = "<redacted>";
-            }
-        }
-        return String.join(" ", parts);
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewaySessionException.java

@@ -1,16 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
-
-public final class MxGatewaySessionException extends MxGatewayException {
-    private final ProtocolStatus protocolStatus;
-
-    public MxGatewaySessionException(String operation, ProtocolStatus protocolStatus) {
-        super(MxGatewayErrors.protocolStatusMessage(operation, protocolStatus));
-        this.protocolStatus = protocolStatus;
-    }
-
-    public ProtocolStatus protocolStatus() {
-        return protocolStatus;
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayWorkerException.java

@@ -1,16 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
-
-public final class MxGatewayWorkerException extends MxGatewayException {
-    private final ProtocolStatus protocolStatus;
-
-    public MxGatewayWorkerException(String operation, ProtocolStatus protocolStatus) {
-        super(MxGatewayErrors.protocolStatusMessage(operation, protocolStatus));
-        this.protocolStatus = protocolStatus;
-    }
-
-    public ProtocolStatus protocolStatus() {
-        return protocolStatus;
-    }
-}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxStatuses.java

@@ -1,48 +0,0 @@
-package com.dohertylan.mxgateway.client;
-
-import mxaccess_gateway.v1.MxaccessGateway.MxStatusCategory;
-import mxaccess_gateway.v1.MxaccessGateway.MxStatusProxy;
-import mxaccess_gateway.v1.MxaccessGateway.MxStatusSource;
-
-public final class MxStatuses {
-    private MxStatuses() {
-    }
-
-    public static boolean succeeded(MxStatusProxy status) {
-        return status == null || status.getSuccess() != 0;
-    }
-
-    public static MxStatusView view(MxStatusProxy status) {
-        return new MxStatusView(status);
-    }
-
-    public record MxStatusView(MxStatusProxy raw) {
-        public int success() {
-            return raw.getSuccess();
-        }
-
-        public MxStatusCategory category() {
-            return raw.getCategory();
-        }
-
-        public MxStatusSource detectedBy() {
-            return raw.getDetectedBy();
-        }
-
-        public int detail() {
-            return raw.getDetail();
-        }
-
-        public int rawCategory() {
-            return raw.getRawCategory();
-        }
-
-        public int rawDetectedBy() {
-            return raw.getRawDetectedBy();
-        }
-
-        public String diagnosticText() {
-            return raw.getDiagnosticText();
-        }
-    }
-}

clients/java/settings.gradle

@@ -16,7 +16,7 @@ dependencyResolutionManagement {
     }
 }
 
-rootProject.name = 'mxaccessgw-java'
+rootProject.name = 'zb-mom-ww-mxaccessgw-java'
 
-include 'mxgateway-client'
-include 'mxgateway-cli'
+include 'zb-mom-ww-mxgateway-client'
+include 'zb-mom-ww-mxgateway-cli'

clients/java/src/main/generated/main/grpc/mxaccess_gateway/v1/MxAccessGatewayGrpc.java

@@ -139,6 +139,99 @@ public final class MxAccessGatewayGrpc {
     return getStreamEventsMethod;
   }
 
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest,
+      mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply> getAcknowledgeAlarmMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "AcknowledgeAlarm",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest,
+      mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply> getAcknowledgeAlarmMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest, mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply> getAcknowledgeAlarmMethod;
+    if ((getAcknowledgeAlarmMethod = MxAccessGatewayGrpc.getAcknowledgeAlarmMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getAcknowledgeAlarmMethod = MxAccessGatewayGrpc.getAcknowledgeAlarmMethod) == null) {
+          MxAccessGatewayGrpc.getAcknowledgeAlarmMethod = getAcknowledgeAlarmMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest, mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "AcknowledgeAlarm"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("AcknowledgeAlarm"))
+              .build();
+        }
+      }
+    }
+    return getAcknowledgeAlarmMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest,
+      mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> getStreamAlarmsMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "StreamAlarms",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest,
+      mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> getStreamAlarmsMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> getStreamAlarmsMethod;
+    if ((getStreamAlarmsMethod = MxAccessGatewayGrpc.getStreamAlarmsMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getStreamAlarmsMethod = MxAccessGatewayGrpc.getStreamAlarmsMethod) == null) {
+          MxAccessGatewayGrpc.getStreamAlarmsMethod = getStreamAlarmsMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "StreamAlarms"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("StreamAlarms"))
+              .build();
+        }
+      }
+    }
+    return getStreamAlarmsMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest,
+      mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> getQueryActiveAlarmsMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "QueryActiveAlarms",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest,
+      mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> getQueryActiveAlarmsMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> getQueryActiveAlarmsMethod;
+    if ((getQueryActiveAlarmsMethod = MxAccessGatewayGrpc.getQueryActiveAlarmsMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getQueryActiveAlarmsMethod = MxAccessGatewayGrpc.getQueryActiveAlarmsMethod) == null) {
+          MxAccessGatewayGrpc.getQueryActiveAlarmsMethod = getQueryActiveAlarmsMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest, mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "QueryActiveAlarms"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("QueryActiveAlarms"))
+              .build();
+        }
+      }
+    }
+    return getQueryActiveAlarmsMethod;
+  }
+
   /**
    * Creates a new async stub that supports all call types for the service
    */
@@ -232,6 +325,44 @@ public final class MxAccessGatewayGrpc {
         io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxEvent> responseObserver) {
       io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getStreamEventsMethod(), responseObserver);
     }
+
+    /**
+     */
+    default void acknowledgeAlarm(mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getAcknowledgeAlarmMethod(), responseObserver);
+    }
+
+    /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
+     */
+    default void streamAlarms(mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getStreamAlarmsMethod(), responseObserver);
+    }
+
+    /**
+     * <pre>
+     * Point-in-time snapshot of the currently-active alarm set served from the
+     * gateway's always-on alarm monitor cache (session-less). Used after a
+     * reconnect to seed Part 9 client state, or to reconcile alarms that may
+     * have been missed during a transport blip. Streamed so callers can
+     * begin processing without buffering the full set.
+     * `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+     * snapshot to alarms whose `alarm_full_reference` starts with the given
+     * prefix; an empty prefix returns the full set.
+     * </pre>
+     */
+    default void queryActiveAlarms(mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getQueryActiveAlarmsMethod(), responseObserver);
+    }
   }
 
   /**
@@ -298,6 +429,47 @@ public final class MxAccessGatewayGrpc {
       io.grpc.stub.ClientCalls.asyncServerStreamingCall(
           getChannel().newCall(getStreamEventsMethod(), getCallOptions()), request, responseObserver);
     }
+
+    /**
+     */
+    public void acknowledgeAlarm(mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getAcknowledgeAlarmMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
+     */
+    public void streamAlarms(mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncServerStreamingCall(
+          getChannel().newCall(getStreamAlarmsMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     * <pre>
+     * Point-in-time snapshot of the currently-active alarm set served from the
+     * gateway's always-on alarm monitor cache (session-less). Used after a
+     * reconnect to seed Part 9 client state, or to reconcile alarms that may
+     * have been missed during a transport blip. Streamed so callers can
+     * begin processing without buffering the full set.
+     * `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+     * snapshot to alarms whose `alarm_full_reference` starts with the given
+     * prefix; an empty prefix returns the full set.
+     * </pre>
+     */
+    public void queryActiveAlarms(mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncServerStreamingCall(
+          getChannel().newCall(getQueryActiveAlarmsMethod(), getCallOptions()), request, responseObserver);
+    }
   }
 
   /**
@@ -348,6 +520,48 @@ public final class MxAccessGatewayGrpc {
       return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
           getChannel(), getStreamEventsMethod(), getCallOptions(), request);
     }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply acknowledgeAlarm(mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getAcknowledgeAlarmMethod(), getCallOptions(), request);
+    }
+
+    /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
+     */
+    @io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
+    public io.grpc.stub.BlockingClientCall<?, mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>
+        streamAlarms(mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
+          getChannel(), getStreamAlarmsMethod(), getCallOptions(), request);
+    }
+
+    /**
+     * <pre>
+     * Point-in-time snapshot of the currently-active alarm set served from the
+     * gateway's always-on alarm monitor cache (session-less). Used after a
+     * reconnect to seed Part 9 client state, or to reconcile alarms that may
+     * have been missed during a transport blip. Streamed so callers can
+     * begin processing without buffering the full set.
+     * `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+     * snapshot to alarms whose `alarm_full_reference` starts with the given
+     * prefix; an empty prefix returns the full set.
+     * </pre>
+     */
+    @io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
+    public io.grpc.stub.BlockingClientCall<?, mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>
+        queryActiveAlarms(mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
+          getChannel(), getQueryActiveAlarmsMethod(), getCallOptions(), request);
+    }
   }
 
   /**
@@ -397,6 +611,46 @@ public final class MxAccessGatewayGrpc {
       return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
           getChannel(), getStreamEventsMethod(), getCallOptions(), request);
     }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply acknowledgeAlarm(mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getAcknowledgeAlarmMethod(), getCallOptions(), request);
+    }
+
+    /**
+     * <pre>
+     * Session-less central alarm feed. The stream opens with the current
+     * active-alarm snapshot (one `active_alarm` per alarm), then a single
+     * `snapshot_complete`, then a `transition` for every subsequent change.
+     * Served by the gateway's always-on alarm monitor; any number of clients
+     * fan out from the single monitor without opening a worker session.
+     * </pre>
+     */
+    public java.util.Iterator<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage> streamAlarms(
+        mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
+          getChannel(), getStreamAlarmsMethod(), getCallOptions(), request);
+    }
+
+    /**
+     * <pre>
+     * Point-in-time snapshot of the currently-active alarm set served from the
+     * gateway's always-on alarm monitor cache (session-less). Used after a
+     * reconnect to seed Part 9 client state, or to reconcile alarms that may
+     * have been missed during a transport blip. Streamed so callers can
+     * begin processing without buffering the full set.
+     * `QueryActiveAlarmsRequest.alarm_filter_prefix` optionally narrows the
+     * snapshot to alarms whose `alarm_full_reference` starts with the given
+     * prefix; an empty prefix returns the full set.
+     * </pre>
+     */
+    public java.util.Iterator<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot> queryActiveAlarms(
+        mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
+          getChannel(), getQueryActiveAlarmsMethod(), getCallOptions(), request);
+    }
   }
 
   /**
@@ -441,12 +695,23 @@ public final class MxAccessGatewayGrpc {
       return io.grpc.stub.ClientCalls.futureUnaryCall(
           getChannel().newCall(getInvokeMethod(), getCallOptions()), request);
     }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply> acknowledgeAlarm(
+        mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getAcknowledgeAlarmMethod(), getCallOptions()), request);
+    }
   }
 
   private static final int METHODID_OPEN_SESSION = 0;
   private static final int METHODID_CLOSE_SESSION = 1;
   private static final int METHODID_INVOKE = 2;
   private static final int METHODID_STREAM_EVENTS = 3;
+  private static final int METHODID_ACKNOWLEDGE_ALARM = 4;
+  private static final int METHODID_STREAM_ALARMS = 5;
+  private static final int METHODID_QUERY_ACTIVE_ALARMS = 6;
 
   private static final class MethodHandlers<Req, Resp> implements
       io.grpc.stub.ServerCalls.UnaryMethod<Req, Resp>,
@@ -481,6 +746,18 @@ public final class MxAccessGatewayGrpc {
           serviceImpl.streamEvents((mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest) request,
               (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxEvent>) responseObserver);
           break;
+        case METHODID_ACKNOWLEDGE_ALARM:
+          serviceImpl.acknowledgeAlarm((mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply>) responseObserver);
+          break;
+        case METHODID_STREAM_ALARMS:
+          serviceImpl.streamAlarms((mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>) responseObserver);
+          break;
+        case METHODID_QUERY_ACTIVE_ALARMS:
+          serviceImpl.queryActiveAlarms((mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>) responseObserver);
+          break;
         default:
           throw new AssertionError();
       }
@@ -527,6 +804,27 @@ public final class MxAccessGatewayGrpc {
               mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
               mxaccess_gateway.v1.MxaccessGateway.MxEvent>(
                 service, METHODID_STREAM_EVENTS)))
+        .addMethod(
+          getAcknowledgeAlarmMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmRequest,
+              mxaccess_gateway.v1.MxaccessGateway.AcknowledgeAlarmReply>(
+                service, METHODID_ACKNOWLEDGE_ALARM)))
+        .addMethod(
+          getStreamAlarmsMethod(),
+          io.grpc.stub.ServerCalls.asyncServerStreamingCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.StreamAlarmsRequest,
+              mxaccess_gateway.v1.MxaccessGateway.AlarmFeedMessage>(
+                service, METHODID_STREAM_ALARMS)))
+        .addMethod(
+          getQueryActiveAlarmsMethod(),
+          io.grpc.stub.ServerCalls.asyncServerStreamingCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.QueryActiveAlarmsRequest,
+              mxaccess_gateway.v1.MxaccessGateway.ActiveAlarmSnapshot>(
+                service, METHODID_QUERY_ACTIVE_ALARMS)))
         .build();
   }
 
@@ -579,6 +877,9 @@ public final class MxAccessGatewayGrpc {
               .addMethod(getCloseSessionMethod())
               .addMethod(getInvokeMethod())
               .addMethod(getStreamEventsMethod())
+              .addMethod(getAcknowledgeAlarmMethod())
+              .addMethod(getStreamAlarmsMethod())
+              .addMethod(getQueryActiveAlarmsMethod())
               .build();
         }
       }

clients/java/src/main/generated/main/java/mxaccess_worker/v1/MxaccessWorker.java

@@ -12608,8 +12608,8 @@ public final class MxaccessWorker extends com.google.protobuf.GeneratedFile {
       "CONVERSION_FAILED\020\010\022\"\n\036WORKER_FAULT_CATE" +
       "GORY_STA_HUNG\020\t\022(\n$WORKER_FAULT_CATEGORY" +
       "_QUEUE_OVERFLOW\020\n\022*\n&WORKER_FAULT_CATEGO" +
-      "RY_SHUTDOWN_TIMEOUT\020\013B\034\252\002\031MxGateway.Cont" +
-      "racts.Protob\006proto3"
+      "RY_SHUTDOWN_TIMEOUT\020\013B&\252\002#ZB.MOM.WW.MxGa" +
+      "teway.Contracts.Protob\006proto3"
     };
     descriptor = com.google.protobuf.Descriptors.FileDescriptor
       .internalBuildGeneratedFileFrom(descriptorData,

clients/java/zb-mom-ww-mxgateway-cli/build.gradle

@@ -3,11 +3,11 @@ plugins {
 }
 
 dependencies {
-    implementation project(':mxgateway-client')
+    implementation project(':zb-mom-ww-mxgateway-client')
     implementation "com.google.protobuf:protobuf-java-util:${protobufVersion}"
     implementation "info.picocli:picocli:${picocliVersion}"
 }
 
 application {
-    mainClass = 'com.dohertylan.mxgateway.cli.MxGatewayCli'
+    mainClass = 'com.zb.mom.ww.mxgateway.cli.MxGatewayCli'
 }