docs: add CHANGELOG, document parent/child trees in README

Start a CHANGELOG.md (Keep-a-Changelog format) anchored at 0.2.0.
Entry documents the breaking changes — Device constructor signature,
removed ID-based parent/child mutators, refresh_all_nodes rename —
alongside the additive features: tree navigation, effective-state
computation, delete protocol, reconnect cascade. Brief 0.1.7 and
0.1.2 entries reference git for pre-changelog history.

README gains a "Device Trees" Quick Start section showing the
parent= constructor pattern, batched state_transition, and 3-level
depth. Controller Role section gains a hierarchy/effective-state
example. Module Structure no longer mentions the removed mqtt.py
(extracted to ebus-mqtt-client at 56ad978). homie.py contents list
adds the new public surface: HOMIE_EFFECTIVE_STATE_TABLE,
DiscoveredDevice hierarchy fields, Controller tree-nav methods.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dcj

CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to `ebus-sdk` are recorded here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases earlier than 0.2.0 predate this file — see `git log` and the corresponding `v0.1.x` tags for details.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-06-11
+
+The 0.2.0 release introduces first-class parent/child device trees on both the device (publisher) and controller (consumer) sides of the SDK. A panel-style root device can now own dozens of child devices that share a single MQTT connection and a single Last Will, and controllers can navigate the resulting tree and compute effective state per the Homie 5 spec without re-implementing the rules per consumer.
+
+### Added
+
+- `Device(parent=<Device>)` constructor argument for building child devices. The child borrows the root's MQTT connection — there is exactly one `MqttClient` per tree and exactly one Last Will registered, on the root's `$state` topic.
+- `Device.root()`, `Device.parent()`, `Device.children()` — live references that walk the tree. `root_id()` / `parent_id()` accessors are now derived from these. Trees may be arbitrary depth (e.g. panel → BESS child → MID grandchild).
+- `Device.delete()` — runs the Homie remove-child protocol (clear retained `$state` / `$description` / property values, detach from parent, re-publish parent's description). Recursive on roots: leaves-first teardown of the whole subtree.
+- `Device.refresh_tree()` — recursive republish of description + nodes + state for every device under this one. Called automatically by `on_connect()` on broker reconnect so the entire tree's retained-state is re-established.
+- `DiscoveredDevice.root_id`, `parent_id`, `children_ids`, `is_root` — hierarchy fields derived from `$description`.
+- `Controller.get_root_devices()`, `get_root(device_id)`, `get_children(device_id)`, `get_descendants(device_id)` — tree-navigation API.
+- `Controller.get_effective_state(device_id)` and the public `HOMIE_EFFECTIVE_STATE_TABLE` module constant — implement the Homie 5 state-precedence rule. When a root is `init` / `disconnected` / `sleeping` / `lost`, every descendant is effectively the same state without each descendant needing to republish.
+
+### Changed
+
+- **BREAKING** — `Device` constructor signature. The previous string-ID args `root_id=`, `parent_id=`, and `children_ids=` are removed; use `parent=<Device>` instead. Pure root-device usage (`Device(id, name, type, mqtt_cfg, ...)`) is unchanged and source-compatible.
+- The `Device._end_state_transition()` → broker sequence now emits exactly one `$state=init` and one `$state=ready` regardless of nesting depth (state transitions are reentrant via an internal depth counter). Previously a nested `with device.state_transition(): with device.state_transition(): ...` emitted a spurious extra INIT/READY cycle from the outer `__exit__`, forcing every controller in the wild to resync unnecessarily.
+- `add_node()` and other structural mutations inside `with parent.state_transition(): ...` now collapse into a single parent `$state=init` → `$description` → `$state=ready` cycle for the whole batch. Building a panel with 32 circuit children produces one observable parent transition, not 32.
+- `Device.publish()`, `delete_all_from_mqtt()`, `clear_retained_topic()`, and the `Property` → `Node` → `Device` publish chain all route through `Device.get_mqtt_client()`, which ascends to `root().mqttc`. There is no behavioral change for root devices; child devices now publish their topics through the root's connection automatically.
+
+### Removed
+
+- **BREAKING** — `Device.add_child(child_id)`. Children are added by constructing them with `parent=<Device>`; the `_children` list is maintained automatically.
+- **BREAKING** — `Device.remove_child(child_id)`. Use `child_device.delete()` instead — it runs the full Homie remove-child protocol rather than just popping an ID from a list.
+- **BREAKING** — `Device.set_parent(parent_id)` and `Device.unset_parent()`. Homie does not support reparenting at the wire level; destroy and reconstruct instead.
+- **BREAKING** — `Device.refresh_all_nodes()`. Renamed to `refresh_tree()` to reflect that it now walks descendants. The old name was misleading: it always published `$description` and `$state` in addition to nodes.
+
+### Fixed
+
+- Recursive `Device.delete()` no longer emits gratuitous `$state=init` / `$state=ready` publishes on dying intermediate devices while the cascade is in progress.
+- Broker reconnect now republishes every device in the tree (description, nodes, property values, state), not just the root.
+
+## [0.1.7] — 2025
+
+### Fixed
+
+- Added `setup.py` shim for legacy setuptools toolchains that can't read `pyproject.toml`-only packages.
+
+## [0.1.2] — 2025
+
+Initial public release on PyPI. See `git log v0.1.2` for the surface that shipped.
+
+[Unreleased]: https://github.com/electrification-bus/python-sdk/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.2.0
+[0.1.7]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.1.7
+[0.1.2]: https://github.com/electrification-bus/python-sdk/releases/tag/v0.1.2

README.md

@@ -46,6 +46,30 @@ device.start_mqtt_client()
 temp.set_value(23.5)
 ```
 
+### Device Trees (parent / child)
+
+Build a tree of devices that share a single MQTT connection. The root device owns the connection (and the Last Will), every child borrows it via the `parent=` constructor arg, and `$description` `root` / `parent` / `children` fields are kept in sync automatically. The tree can be any depth.
+
+```python
+panel = Device('panel-1', type='energy.ebus.device.electrical-panel', mqtt_cfg={...})
+panel.start_mqtt_client()
+
+# Add 32 circuit children inside one state transition — the broker sees
+# exactly one INIT→READY cycle on the panel, not 32.
+with panel.state_transition():
+    for cid in commissioned_circuits:
+        Device(id=cid, type='energy.ebus.device.circuit', parent=panel)
+
+# Three-level tree: panel → BESS child → MID grandchild
+bess = Device(id='bess-1', type='...battery-storage', parent=panel)
+Device(id='mid-1', type='...metering', parent=bess)
+
+# Remove a child at runtime (runs the Homie remove-child protocol)
+panel.children()[0].delete()
+```
+
+Children may have children of their own. A single Last Will registered on the root marks the entire tree `lost` if the publisher process dies — controllers compute effective state per the Homie 5 precedence table (see [`HOMIE_EFFECTIVE_STATE_TABLE`](src/ebus_sdk/homie.py)).
+
 ### Controller Role
 
 Discover and monitor Homie devices:
@@ -65,33 +89,43 @@ controller.set_on_property_changed_callback(on_property_changed)
 controller.start_discovery()
 ```
 
+Controllers can also navigate device hierarchies and compute effective state:
+
+```python
+# Walk the tree
+roots = controller.get_root_devices()
+for root in roots:
+    for descendant in controller.get_descendants(root.device_id):
+        # When the root is lost/disconnected/sleeping/init, every descendant
+        # is effectively the same regardless of its own reported $state.
+        print(f'{descendant.device_id}: {controller.get_effective_state(descendant.device_id)}')
+```
+
 ## Module Structure
 
 ```
 src/ebus_sdk/
 ├── __init__.py     # Package exports
-├── homie.py        # Homie convention implementation
-├── mqtt.py         # MQTT client wrapper
-└── property.py     # Property abstractions
+├── homie.py        # Homie convention implementation (Device, Node, Property, Controller, ...)
+└── property.py     # Application-level property abstractions
 ```
 
+MQTT transport lives in the separate [`ebus-mqtt-client`](https://github.com/electrification-bus/ebus-mqtt-client) package; this SDK depends on it.
+
 ### homie.py
 
 Core Homie convention implementation:
 
-- **Device** - Represents a Homie device with nodes and properties
+- **Device** - Represents a Homie device; pass `parent=` to build a child in a tree
 - **Node** - Groups related properties within a device
 - **Property** - Individual data points (sensors, controls)
-- **Controller** - Discovers and monitors Homie devices on a broker
-- **DiscoveredDevice** - Represents a device found by the controller
+- **Controller** - Discovers and monitors Homie devices on a broker; navigates trees and computes effective state
+- **DiscoveredDevice** - Represents a device found by the controller; exposes `root_id`, `parent_id`, `children_ids`, `is_root`
 - **DeviceState** - Enum: `init`, `ready`, `disconnected`, `sleeping`, `lost`
+- **HOMIE_EFFECTIVE_STATE_TABLE** - Homie 5 state-precedence table used by `Controller.get_effective_state()`
 - **PropertyDatatype** - Enum: `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `ENUM`, `COLOR`, `DATETIME`, `DURATION`, `JSON`
 - **Unit** - Common units: `DEGREE_CELSIUS`, `PERCENT`, `WATT`, `KILOWATT_HOUR`, etc.
 
-### mqtt.py
-
-- **MqttClient** - Wrapper around paho-mqtt with automatic reconnection, TLS support, and subscription management
-
 ### property.py
 
 Application-level property abstractions for bridging application state to Homie:
@@ -110,6 +144,10 @@ See [`examples/README.md`](examples/README.md) for example scripts demonstrating
 - Python 3.10+
 - paho-mqtt >= 1.6.1
 
+## Releases
+
+See [CHANGELOG.md](CHANGELOG.md). 0.2.0 introduces parent/child device trees and contains breaking changes to the `Device` constructor — see the changelog entry before upgrading from 0.1.x.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file Discussions, Issues, and pull requests. Pure MQTT-transport changes (TLS, auth, paho upgrades) belong in [`ebus-mqtt-client`](https://github.com/electrification-bus/ebus-mqtt-client), not here. Normative behavior tracks the [Electrification Bus specification](https://github.com/electrification-bus/specification).