diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf5c05a..503bc66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.2.1
+
+- Clarify discovery migration and entity documentation, including the choices
+  for new devices, existing installations, and no-device-discovery projects.
+- Refresh the canonical PlatformIO and Arduino IDE package metadata.
+
 ## 3.2.0
 
 **Discovery publication and resilience:**
diff --git a/README.md b/README.md
index f6b8458..50d9911 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ Build [ESP Sensor](examples/01-esp-sensor/) for a complete ESP8266/ESP32 project
 
 ```ini
 lib_deps =
-    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.0
+    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.1
 ```
 
 PlatformIO clones the Git repository and checks out the ref after `#`; that ref is a release tag, not a GitHub Release asset. Arduino IDE is supported through the included [`library.properties`](library.properties).
diff --git a/docs/device-and-discovery.md b/docs/device-and-discovery.md
index d3449d1..3976c76 100644
--- a/docs/device-and-discovery.md
+++ b/docs/device-and-discovery.md
@@ -51,9 +51,19 @@ mqtt.setDataPrefix("myDataPrefix");
 
 Both formats remain supported by Home Assistant. Device discovery requires Home Assistant **2024.11.0 or newer**. Use `enableDeviceDiscovery()` only for a new device which has never published this library's single-component discovery topics.
 
+Choose the mode before connecting a device:
+
+- **New device:** call `enableDeviceDiscovery()` before connecting.
+- **Existing device using single-component discovery:** follow the migration
+  procedure below.
+- **No need for device discovery:** keep the default behavior.
+
 ### Migrating an existing device to device discovery
 
-Do not switch an existing device by calling `enableDeviceDiscovery()` alone. Home Assistant derives an entity's discovery identity from the topic, and a direct switch causes retained-topic conflicts. The migration deliberately publishes, in order:
+Do not switch an existing device by calling `enableDeviceDiscovery()` alone.
+Home Assistant derives an entity's discovery identity from the topic, and a
+direct switch causes retained-topic conflicts. The migration publishes, in
+order:
 
 1. `{"migrate_discovery":true}` to every old retained component config topic;
 2. the retained `/device/<deviceId>/config` payload; and only then
diff --git a/docs/entities.md b/docs/entities.md
index 5e91799..6f37867 100644
--- a/docs/entities.md
+++ b/docs/entities.md
@@ -22,7 +22,9 @@ ArduinoHA supports these Home Assistant MQTT discovery entity classes. Choose th
 | Tag scanner | [tag-scanner](../examples/tag-scanner/tag-scanner.ino) |
 | Text | Use the API header; no dedicated sketch yet |
 
-The library does not currently implement alarm control panels, events, humidifiers, images, lawn mowers, sirens, updates, vacuums, valves, or water heaters. Those are deliberate unsupported surfaces, not configuration switches.
+The library does not currently implement alarm control panels, events,
+humidifiers, images, lawn mowers, sirens, updates, vacuums, valves, or water
+heaters. They cannot be enabled through configuration.
 
 ## Common lifecycle
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c09c9b4..26a2e72 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -11,7 +11,7 @@ ArduinoHA talks to Home Assistant over **MQTT** (TCP). You need an MQTT broker r
 
 ```ini
 lib_deps =
-    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.0
+    home-assistant-integration=https://github.com/alexhopeoconnor/arduino-home-assistant.git#v3.2.1
 ```
 
 **Arduino IDE:** this fork is not indexed by Library Manager. Download the
diff --git a/library.json b/library.json
index ae48729..2df9d52 100644
--- a/library.json
+++ b/library.json
@@ -1,6 +1,6 @@
 {
   "name": "home-assistant-integration",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "Maintained Home Assistant MQTT discovery and entity integration for Arduino and ESP devices.",
   "keywords": [
     "mqtt",
diff --git a/library.properties b/library.properties
index 6594fbd..ad362b1 100644
--- a/library.properties
+++ b/library.properties
@@ -1,5 +1,5 @@
 name=home-assistant-integration
-version=3.2.0
+version=3.2.1
 author=Dawid Chyrzynski <dev@chyrzynski.pl>, Alex Hope-O'Connor <alex.hope.oconnor@pomonaqld.au>
 maintainer=Alex Hope-O'Connor <alex.hope.oconnor@pomonaqld.au>
 sentence=Home Assistant MQTT integration for Arduino
diff --git a/src/ArduinoHADefines.h b/src/ArduinoHADefines.h
index 2c1c35d..1a09f28 100644
--- a/src/ArduinoHADefines.h
+++ b/src/ArduinoHADefines.h
@@ -32,7 +32,7 @@
 #endif
 
 // Current library version used in discovery origin metadata.
-#define ARDUINOHA_LIBRARY_VERSION "3.2.0"
+#define ARDUINOHA_LIBRARY_VERSION "3.2.1"
 
 #if defined(ARDUINOHA_DEBUG)
     #include <Arduino.h>