Document Home Assistant discovery overrides

docs/guide/configuration/devices-groups.md

@@ -78,7 +78,7 @@ sure to set `mqtt.version` to `5` (see `mqtt` configuration above)
 QoS level for MQTT messages of this device. [What is QoS?](https://www.npmjs.com/package/mqtt#about-qos)
 
 **`homeassistant`**  
-Allows overriding the values of the Home Assistant discovery payload. See example above.
+Allows overriding the values of the Home Assistant discovery payload. Overrides can be set globally for the device or for a specific discovered entity under its `object_id`; setting a property to `null` removes it from the discovery payload. See [Home Assistant discovery overrides](../usage/integrations/home_assistant.md#overriding-discovery-properties) for examples.
 
 **`debounce`**  
 Debounces messages of this device. When setting e.g. `debounce: 1` and a message from a device is

docs/guide/usage/integrations/home_assistant.md

@@ -117,6 +117,11 @@ Group discovery properties can be overridden via `groups.<id>.homeassistant` in
 
 Any Home Assistant MQTT discovery property can be overridden on a device. Two examples are shown below. For a full and current list of discovery properties, see [the Home Assistant MQTT Discovery integration](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) and [the Home Assistant extension](https://github.com/Koenkk/zigbee2mqtt/blob/03ba647dc6b5f299f8f3ab441712999fcb3a253e/lib/extension/homeassistant.ts) in the Zigbee2MQTT source code.
 
+Overrides can be set at the device level or for a specific discovered entity under its `object_id`.
+The entity `object_id` is the part used in the Home Assistant discovery payload, for example `light`, `cover`, `climate`, `temperature`, or a generated composite child such as `manual_default_settings_irrigation_duration`.
+Device-specific overrides are applied after Zigbee2MQTT's built-in compatibility mappings, so they can be used to remove or adjust discovery properties that do not match your installation.
+Set a discovery property to `null` to remove it from the Home Assistant discovery payload.
+
 ### Changing `supported_color_modes`
 
 This is useful for switching light bulbs from reporting values from X/Y (which is the default) to reporting in hue / saturation (which is what bulbs report color in when changing via hue or saturation, such as with the `hue_move` and `saturation_move` commands).
@@ -165,6 +170,50 @@ devices:
                 state_value_template: '{{ value_json.state_right }}'
 ```
 
+### Removing unsupported capabilities
+
+Some devices expose generic capabilities that are not useful for every installation. For example, a cover controller can expose tilt controls even when it is connected to a roller blind without slats, or a thermostat discovery payload can expose modes that should not be offered in Home Assistant. These can be adjusted with per-entity discovery overrides.
+
+This example removes the Home Assistant tilt command/status properties from a discovered cover:
+
+```yaml
+devices:
+    '0x12345678':
+        friendly_name: living_room_blind
+        homeassistant:
+            cover:
+                tilt_command_topic: null
+                tilt_status_topic: null
+                tilt_status_template: null
+                tilt_min: null
+                tilt_max: null
+                tilt_closed_value: null
+                tilt_opened_value: null
+```
+
+This example limits a climate entity to the modes that should be offered by Home Assistant:
+
+```yaml
+devices:
+    '0x12345678':
+        friendly_name: hallway_thermostat
+        homeassistant:
+            climate:
+                modes: ['off', 'heat', 'auto']
+```
+
+### Composite controls
+
+When a Zigbee2MQTT expose is a settable composite with numeric or enum child features, Zigbee2MQTT also creates dedicated Home Assistant `number` or `select` entities for those child features. The original composite sensor remains available for viewing the full object.
+
+For example, a composite property named `manual_default_settings` with a numeric child property named `irrigation_duration` is discovered as a Home Assistant number entity using the object ID `manual_default_settings_irrigation_duration`. When changed from Home Assistant it publishes only the changed child field:
+
+```json
+{"manual_default_settings": {"irrigation_duration": 30}}
+```
+
+If a device requires the full composite object when setting a child field, its converter must merge this partial payload with the current state or expose a non-composite control instead.
+
 ### Changing device properties
 
 As an advanced example to show changing any MQTT property can be overridden, the following configuration changes the `suggested_area` property of the `device`. The example shows that you can just copy the given MQTT discovery hierarchy underneath the `homeassistant` property (given that `suggested_area` is underneath the `device` property). Please note, that other `device` properties are possibly set by Zigbee2MQTT (e.g. `manufacturer`).