Document ESPHome reconfig and name conflict resolution (#38680)

source/_integrations/esphome.markdown

@@ -100,3 +100,42 @@ The entity will be named `livingroomdesk Temperature` and will default to having
       data:
         homeassistant.components.esphome: debug
       ```
+
+## Reconfiguration and Device Replacement
+
+This integration supports reconfiguration, allowing you to make changes—such as updating the IP address—even after a device has already been set up.
+
+### Name Conflict Resolution
+
+If Home Assistant detects multiple devices with the same [**name**](https://esphome.io/components/esphome.html#configuration-variables), it will automatically initiate **Name Conflict Resolution**. This process is designed to help you seamlessly replace a failed or retired device with new hardware, while preserving your existing configuration if desired.
+
+This process gives you two options:
+
+- **Migrate**: Transfers the existing entity configuration to the new device. This preserves all your settings, entity names, and history. Use this when you're replacing the hardware but keeping the same YAML configuration.
+- **Overwrite**: Replaces the existing configuration with the new device.
+  **Caution:** This will **erase all existing settings** for the old device including entity names, customizations, and history will be lost. Use this only if the new device is completely different and you don’t need anything from the previous setup.
+
+{% tip %}
+If you’re using the same YAML file on the new device, choose **Migrate**. If it’s a totally different device (even if it shares the same name), **Overwrite** is the safer option.
+{% endtip %}
+
+---
+
+### Requirements for Name Conflict Resolution
+
+To trigger Name Conflict Resolution, all of the following must be true:
+
+- The new device must be running **ESPHome 2025.4.0 or later**.
+- The new device must use the same [**name**](https://esphome.io/components/esphome.html#configuration-variables) (not just the friendly name).
+- The original (old) device must be **offline**.
+
+---
+
+### How to Trigger Name Conflict Resolution
+
+You can trigger Name Conflict Resolution in several ways:
+
+- Connecting a new device with the same name and a **static IP address** will automatically launch a repair flow.
+- Using the **Reconfigure** option in the UI to point to a different IP that hosts a device with the same name.
+- Configuring a **newly discovered device** that uses the same name.
+- **Manually adding** a device with the same name via the integration setup.