docs(plugin_configuration): clarify clusterName uniqueness scope

documentation/web/docs/user/plugin_configuration.md

@@ -365,6 +365,32 @@ spec:
 This can be useful working with backups from different clusters, for example
 when restoring clusters or configuring replica clusters.
 
+:::warning Uniqueness across namespaces
+`clusterName` is the sole identity key for a cluster's WAL/backup stream
+on the Klio server it is registered with. It must be unique among all
+clusters backed by the same Klio server, regardless of the Kubernetes
+namespace they live in. Two clusters in different namespaces that share
+a `clusterName` on the same server are not a supported configuration:
+the second cluster to connect will have its WAL streaming rejected by
+the server with an error such as:
+
+```
+during server-side replication point validation: rpc error:
+code = InvalidArgument
+desc = invalid system ID, expected "<the other cluster's system ID>"
+```
+
+This is expected, safe behavior: the server detects the mismatched
+system ID and refuses to mix data from the two clusters. If you hit
+this error, check whether another cluster on the same server is
+already using the same `clusterName`.
+
+This also applies across time: deleting a cluster and later reusing its
+`clusterName` on the same server hits the same error, since the server
+can't tell the old cluster is gone. Use a different `clusterName` even for
+unrelated clusters that reuse a retired one.
+:::
+
 ### Tier 2 configuration
 
 Tier 2 provides secondary storage (typically object storage like S3) for