From b77ed324bd294ea9e0bf42b572208c58294d38ec Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Tue, 22 Apr 2025 10:03:16 -1000
Subject: [PATCH] Restore missing ESPHome docs

This section was lost in a merge conflict resolution
of current -> next
---
 source/_integrations/esphome.markdown | 41 ++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/source/_integrations/esphome.markdown b/source/_integrations/esphome.markdown
index 2e39ec30d343..a7887c05bd18 100644
--- a/source/_integrations/esphome.markdown
+++ b/source/_integrations/esphome.markdown
@@ -211,8 +211,47 @@ If you want the device to send logs without requiring you to be actively monitor
         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.
+
 ## Known Limitations
 
 Each ESPHome device must have a **unique name**. This name is important for mDNS announcements, ensuring that the device can be properly discovered, quickly reconnected when it comes online or wakes from deep sleep (for devices that support deep sleep), and correctly linked to the [**ESPHome Device Builder Add-on**](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon). It's also crucial for **DHCP discovery** if mDNS is not available.
 
-Using duplicate names can lead to connection issues, failed discovery, and unexpected behavior with both the integration and the add-on.
+Using duplicate names can lead to connection issues, failed discovery, and unexpected behavior with both the integration and the add-on.
\ No newline at end of file