feat: finalize documentation and validation (Task 7)

- Rewrite project CLAUDE.md to match actual C/Unity implementation and modules
- Add docs/hardware_connection_diagram.md (ESP32-C6 <-> Ballu AC wiring)
- Add docs/home_assistant_integration.md (HA usage examples)
- Update Readme.md doc index and fix unclosed code fence
- Validate docs against implementation (build + all tests pass)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/hardware_connection_diagram.md

@@ -0,0 +1,98 @@
+# Hardware Connection Diagram: ESP32-C6 ↔ Ballu AC
+
+This document describes the physical wiring between the ESP32-C6 controller and
+the Ballu air conditioner's MideaUART port, and the logical signal path through
+the firmware.
+
+> Pin numbers below match the firmware defaults in `src/app_controller.c`
+> (`apply_default_uart_config`): **TX = GPIO16**, **RX = GPIO17**, 9600 baud, 8N1.
+> These are configurable via `app_controller_config_t.uart_config`.
+
+## 1. Signal Overview
+
+```
++---------------------+        UART 9600 8N1        +---------------------+
+|                     |   (50 ms command spacing)   |                     |
+|   Home Assistant    |                             |     Ballu AC unit   |
+|   (Zigbee coord.)   |                             |   (Midea UART bus)  |
+|                     |                             |                     |
++----------+----------+                             +----------+----------+
+           |                                                   |
+    Zigbee 2.4 GHz (802.15.4)                          3.3V TTL UART
+           |                                                   |
++----------v---------------------------------------------------v----------+
+|                          ESP32-C6 controller                            |
+|                                                                         |
+|  [Zigbee radio] --> zigbee_zcl --> integration_layer --> midea_protocol |
+|                                          |                    |         |
+|                                          v                    v         |
+|                                   status_monitor  <-->   uart_driver    |
+|                                                              |          |
+|                                          GPIO16 (TX) --------+          |
+|                                          GPIO17 (RX) --------+          |
++-------------------------------------------------------------------------+
+```
+
+## 2. Physical Wiring (ESP32-C6 ↔ AC MideaUART header)
+
+The Ballu/Midea indoor unit exposes a 3-wire (or 4-wire) TTL UART header. The AC
+side already provides regulated power on some models; **verify the voltage on the
+AC connector before wiring** — the ESP32-C6 GPIO are strictly 3.3V tolerant.
+
+| ESP32-C6 pin | Direction | AC MideaUART pin | Notes |
+| :-- | :--: | :-- | :-- |
+| GPIO16 (TX)  | ESP → AC | RX  | Controller transmits commands to the AC |
+| GPIO17 (RX)  | AC → ESP | TX  | Controller receives status frames from the AC |
+| GND          | common   | GND | **Mandatory** common ground reference |
+| 3V3          | power    | +5V/+12V | Do **not** connect AC +5V/+12V directly to 3V3; use a suitable regulator if powering the ESP32-C6 from the AC |
+
+```mermaid
+graph LR
+    subgraph AC [Ballu AC - Midea UART header]
+        ARX[RX]
+        ATX[TX]
+        AGND[GND]
+        APWR[+5V / +12V]
+    end
+
+    subgraph ESP [ESP32-C6 controller]
+        ETX[GPIO16 TX]
+        ERX[GPIO17 RX]
+        EGND[GND]
+        E3V3[3V3]
+    end
+
+    ETX -->|3.3V TTL| ARX
+    ATX -->|3.3V TTL| ERX
+    EGND --- AGND
+    APWR -.->|via 3.3V regulator only| E3V3
+```
+
+## 3. Wiring Rules
+
+- **Cross TX/RX**: controller TX (GPIO16) → AC RX; AC TX → controller RX (GPIO17).
+- **Common ground is mandatory** — floating grounds cause framing errors.
+- **3.3V logic only.** If the AC UART header uses 5V logic, insert a logic-level
+  shifter between the boards.
+- **Power isolation.** Never feed the AC's raw supply rail into the ESP32-C6 3V3
+  pin; step it down with a regulator (or power the ESP32-C6 over USB during
+  development).
+- **Strapping pins.** GPIO16/GPIO17 are the ESP32-C6 default UART0 pins used for
+  boot logging/flashing. When wiring the AC to these pins, disconnect the AC
+  during flashing, or remap the AC UART to spare GPIO via
+  `uart_config_t.tx_pin` / `rx_pin` to keep the boot console free.
+
+## 4. Firmware Signal Path
+
+- **Command path (HA → AC):**
+  `zigbee_zcl` receives a ZCL Thermostat command → `integration_layer` maps
+  `system_mode`/temperature to a `midea_control_t` → `midea_protocol` encodes the
+  frame → `uart_driver` transmits it on GPIO16 with ≥50 ms spacing.
+- **Feedback path (AC → HA):**
+  `uart_driver` reads a frame on GPIO17 → `midea_protocol` decodes it to
+  `midea_status_t` → `status_monitor` runs fault detection + watchdog and maps to
+  `zcl_thermostat_attrs_t` → `zigbee_zcl` publishes `local_temperature` and
+  `system_mode` for Home Assistant.
+
+See `docs/Hardware integration guide.md` for detailed ESP32-C6 pinout, strapping
+pin cautions, and PCB layout guidance.