add docs for hostname collision setting (#1051)

src/pages/manage/dns/index.mdx

@@ -18,6 +18,8 @@ NetBird provides centralized DNS management to help your peers resolve domain na
 
 Starting with [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name to each peer in a private `netbird.cloud` space. You can access machines using names like `my-server.netbird.cloud` instead of IP addresses.
 
+When two peers in an account share a hostname, the second one gets an IP-based suffix such as `my-server-12-7.netbird.cloud` by default. You can make such registrations fail instead with the [Unique Peer Hostnames](/manage/settings/clients#unique-peer-hostnames) setting.
+
 <Note>
 Available on both NetBird Cloud and self-hosted versions running v0.11.0 or later.
 </Note>

src/pages/manage/settings/clients.mdx

@@ -1,5 +1,5 @@
 export const description =
-    'Configure account-wide client behavior: automatic updates, lazy connections, and exposing services from the CLI.'
+    'Configure account-wide client behavior: automatic updates, lazy connections, exposing services from the CLI, and unique peer hostnames.'
 
 # Client Settings
 
@@ -29,6 +29,24 @@ Instead of maintaining always-on connections, NetBird can activate peer connecti
 
 See [Lazy Connections](/manage/peers/lazy-connection) for how activation works, inactivity thresholds, and per-client overrides.
 
+## Unique Peer Hostnames
+
+Two machines in one account can register with the same hostname, for example similar VMs that a provisioning tool all named `laptop`. Every peer still needs its own DNS name, so by default NetBird keeps the registration and adds the last two octets of the peer's NetBird IP to the DNS label: a second `laptop` that gets the IP `100.64.12.7` becomes `laptop-12-7.netbird.cloud`. Renaming a peer to a name another peer already uses gets the same suffix.
+
+The suffix keeps every peer reachable, but it also hides the duplicate. If you want a registration with a duplicate hostname to fail loudly instead, enable the `Reject Hostname Collisions` toggle. With the toggle on:
+
+- A peer registering with a hostname that another peer in the account already uses is rejected. The client reports `peer with hostname "laptop" is already registered`, stops retrying, and stays disconnected until it logs in again with a different hostname.
+- Renaming a peer in the dashboard or through the API to a name another peer already uses fails with the same error.
+- Ephemeral peers are treated exactly like other peers.
+
+Collisions are matched on the DNS label, not the raw hostname. The label is the hostname lowercased with characters that are not valid in DNS replaced by `-`, so `Laptop` and `laptop` collide, and so do `my_laptop` and `my-laptop`.
+
+Enabling the toggle does not touch existing peers: labels that already carry a suffix keep it, and a peer logging in again under its own name is not a collision. Deleting a peer frees its name for the next registration. To let a rejected peer join, give the machine a unique hostname or start the client with one: `netbird up --hostname <name>`.
+
+Keep the toggle off if your fleet registers machines with identical hostnames on purpose, such as autoscaled VMs or containers that join through a [setup key](/manage/peers/register-machines-using-setup-keys). The default suffix exists for that case, and with the toggle on every such machine after the first fails to join.
+
+This setting is available on NetBird Cloud and on self-hosted management servers running v0.81.0 or later. In the API it is the `peer_hostname_collision_rejected` field of the [account settings](/ipa/resources/accounts).
+
 ## Agent Network-focused view
 
 Accounts using [Agent Network](/agent-network) see an additional `Agent Network focused view` toggle. When enabled, the dashboard shows only the Agent Network-related sections and hides parts that are not relevant for it, such as Networks, DNS, and Reverse Proxy. Disable it to bring back the full dashboard.