diff --git a/docs/HOME_ASSISTANT_INTEGRATION.md b/docs/HOME_ASSISTANT_INTEGRATION.md
new file mode 100644
index 0000000..0b6dc25
--- /dev/null
+++ b/docs/HOME_ASSISTANT_INTEGRATION.md
@@ -0,0 +1,38 @@
+# Home Assistant integration plan for WB55cgu
+
+This project currently uses direct Zigbee endpoint reports in `App/` and `STM32_WPAN`.
+
+To connect data to Home Assistant, do this:
+
+1. Keep the current Zigbee role logic in place.
+2. Add a small gateway path from local Zigbee payload -> MQTT JSON by using:
+   - `WB55cgu/App` report callbacks
+   - a publisher to local gateway (if your setup is via USB/serial) or via TCP socket from a bridge.
+3. Use existing Home Assistant server files at:
+   - `..\home-assistant-server\homeassistant\configuration.yaml`
+   - `..\home-assistant-server\mosquitto\config\mosquitto.conf`
+   - `..\home-assistant-server\zigbee2mqtt\configuration.yaml`
+4. Push the telemetry payload to:
+   - `home/stm32wb55/device_001/telemetry`
+5. Status topic:
+   - `home/stm32wb55/device_001/status`
+6. Optional command topic:
+   - `home/stm32wb55/device_001/commands`
+
+Recommended first milestone:
+- send fields: `temperature`, `humidity`, `battery`, `rssi`, `uptime`, `fw_version`
+- value JSON example:
+```json
+{
+  "device_id": "stm32wb55_001",
+  "temperature": 23.4,
+  "humidity": 48.2,
+  "battery": 3.01,
+  "rssi": -67,
+  "uptime": 123456,
+  "fw_version": "0.1.0"
+}
+```
+
+The template protocol definition for this format is in:
+- `..\stm32wb55\protocol.md`