clients: document supervisory/array-write parity gotchas and add advise-supervisory to all CLIs

A consuming project hit two MXAccess parity surprises: a plain Write only
records its user_id when the item has an active supervisory advise (the path
to take when not authenticating), and array writes replace the whole array
rather than patching individual elements. Document both across the five client
READMEs and gateway.md's compatibility baseline, and expose the missing
advise-supervisory subcommand in the go/python/rust/java CLIs (plus the .NET
help text) so callers can establish the supervisory advise without dropping to
the raw command API.

clients/rust/README.md

@@ -125,6 +125,49 @@ preserving the raw message for parity diagnostics. Command replies whose
 protocol status is not `PROTOCOL_STATUS_CODE_OK` become `Error::Command` and
 retain the raw `MxCommandReply`.
 
+## Write Semantics And Common Pitfalls
+
+These are MXAccess parity behaviors that surprise new callers. The gateway
+forwards them unchanged — it does not paper over them.
+
+### Attributing a write to a user without `authenticate_user`
+
+MXAccess only stamps a plain `write`/`write2` with a Galaxy user id when the
+item carries an active *supervisory* advise. If you are **not** using the
+verified/secured path (`authenticate_user` → `write_secured`/`write_secured2`)
+but still need the write attributed to a user id, you must first advise the
+item supervisory and then pass that user id on the write. Without the
+supervisory advise the `user_id` on a plain write is ignored.
+
+The session exposes `advise`/`un_advise` but not supervisory advise, so send it
+through the generic command channel:
+
+```rust
+session
+    .invoke(
+        MxCommandKind::AdviseSupervisory,
+        Payload::AdviseSupervisory(AdviseSupervisoryCommand {
+            server_handle,
+            item_handle,
+        }),
+    )
+    .await?;
+
+session.write(server_handle, item_handle, value, user_id).await?;
+```
+
+The CLI exposes the same command as `advise-supervisory`, and `write` /
+`write2` take `--user-id`.
+
+### Array writes replace the whole array
+
+A write to an array attribute **replaces the entire array**; it is not an
+element-wise patch. To change a subset of elements, send the full array with
+the unchanged elements included. For example, to change 2 elements of a
+20-element array, build the `MxValue` from all 20 values (the 18 unchanged plus
+the 2 new ones). Sending only the 2 changed values overwrites the attribute
+with a 2-element array.
+
 ## Galaxy Repository browse
 
 The Galaxy Repository service exposes a read-only browse over the AVEVA System

clients/rust/crates/mxgw-cli/src/main.rs

@@ -21,10 +21,11 @@ use serde_json::Value;
 use zb_mom_ww_mxgateway_client::galaxy::{BrowseChildrenOptions, LazyBrowseNode};
 use zb_mom_ww_mxgateway_client::generated::galaxy_repository::v1::DeployEvent;
 use zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::{
-    alarm_feed_message, AcknowledgeAlarmRequest, AlarmFeedMessage, CloseSessionRequest, MxCommand,
-    MxCommandKind, MxCommandRequest, MxEvent, MxEventFamily, MxValue as ProtoMxValue,
-    OpenSessionRequest, PingCommand, StreamAlarmsRequest, StreamEventsRequest, Write2BulkEntry,
-    WriteBulkEntry, WriteSecured2BulkEntry, WriteSecuredBulkEntry,
+    alarm_feed_message, AcknowledgeAlarmRequest, AdviseSupervisoryCommand, AlarmFeedMessage,
+    CloseSessionRequest, MxCommand, MxCommandKind, MxCommandRequest, MxEvent, MxEventFamily,
+    MxValue as ProtoMxValue, OpenSessionRequest, PingCommand, StreamAlarmsRequest,
+    StreamEventsRequest, Write2BulkEntry, WriteBulkEntry, WriteSecured2BulkEntry,
+    WriteSecuredBulkEntry,
 };
 use zb_mom_ww_mxgateway_client::{
     next_correlation_id, ApiKey, ClientOptions, Error, GalaxyClient, GatewayClient, MxValue,
@@ -105,6 +106,18 @@ enum Command {
         #[arg(long)]
         json: bool,
     },
+    AdviseSupervisory {
+        #[command(flatten)]
+        connection: ConnectionArgs,
+        #[arg(long)]
+        session_id: String,
+        #[arg(long)]
+        server_handle: i32,
+        #[arg(long)]
+        item_handle: i32,
+        #[arg(long)]
+        json: bool,
+    },
     SubscribeBulk {
         #[command(flatten)]
         connection: ConnectionArgs,
@@ -647,6 +660,27 @@ async fn dispatch(command: Command) -> Result<(), Error> {
             session.advise(server_handle, item_handle).await?;
             print_ok("advise", json);
         }
+        Command::AdviseSupervisory {
+            connection,
+            session_id,
+            server_handle,
+            item_handle,
+            json,
+        } => {
+            let session = session_for(connection, session_id).await?;
+            session
+                .invoke(
+                    MxCommandKind::AdviseSupervisory,
+                    zb_mom_ww_mxgateway_client::generated::mxaccess_gateway::v1::mx_command::Payload::AdviseSupervisory(
+                        AdviseSupervisoryCommand {
+                            server_handle,
+                            item_handle,
+                        },
+                    ),
+                )
+                .await?;
+            print_ok("advise-supervisory", json);
+        }
         Command::SubscribeBulk {
             connection,
             session_id,