Add Home Assistant setup documentation

Covers HAOS VM setup, Xiaomi/Gree/Tuya integrations, visionOS theme,
Mushroom Cards dashboards (mobile + desktop), and known issues.

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

docs/wip/HOME-ASSISTANT-SETUP.md

@@ -0,0 +1,111 @@
+# Home Assistant Setup
+
+**Status:** IN PROGRESS
+**Priority:** High
+**Started:** 2026-02-07
+
+## Overview
+
+Home Assistant OS (HAOS) running as a libvirt VM on Unraid, with custom dashboards, themes, and smart home integrations.
+
+## Infrastructure
+
+| Component | Detail |
+|-----------|--------|
+| VM | HAOS on libvirt (Unraid host) |
+| IP | 192.168.10.50 (VLAN 10 — Management) |
+| Access | Web UI at `http://192.168.10.50:8123` |
+| VM Management | `virsh qemu-agent-command "Home Assistant"` from Unraid |
+| Container | `homeassistant` Docker container inside HAOS |
+
+## Completed
+
+### Integrations
+
+| Integration | Type | Devices | Notes |
+|-------------|------|---------|-------|
+| Gree AC (manual) | Custom component (`gree_manual`) | 1 AC unit | Cross-VLAN via L3 unicast; generic key `a3K8Bx%2r8Y7#xDh` |
+| Xiaomi Miot | HACS integration (`xiaomi_miot`) | 11 devices | 2FA verification required; BLE sensors work via cloud |
+| Tuya / Smart Life | Built-in | Smart Curtain, switches, lights | Paired via Smart Life QR code |
+| Roborock | Via Xiaomi Miot | S7 Pro Ultra | On 192.168.31.x (Xiaomi router subnet) |
+
+**Xiaomi devices discovered:**
+- 4x Miaomiaoce BLE temp/humidity sensors (Living Room, Kitchen, Boys Room, Bedroom)
+- 2x Air Purifiers (Living Room — zhimi.mc1, Boys Room — cpa4)
+- 1x Air Purifier 4 Compact (on VLAN 30)
+- 1x Humidifier (Living Room — deerma.jsq2w)
+- 1x Roborock S7 Pro Ultra
+- 1x Xiaomi Router
+- 1x Mi Smart Home Hub
+
+### Theme — visionOS
+
+| File | Path (inside HA) | Source |
+|------|-------------------|--------|
+| visionOS theme | `/config/themes/visionos.yaml` | [homeassistant-visionos-theme](https://github.com/Nezz/homeassistant-visionos-theme) |
+| Liquid Glass theme | `/config/themes/liquid_glass.yaml` | Same repo |
+| card-mod.js (v4.2.0) | `/config/www/card-mod.js` | Enables backdrop-filter CSS effects |
+| Mushroom Cards (v5.0.10) | `/config/www/mushroom.js` | Clean card collection for dashboards |
+
+- Both JS files registered as Lovelace resources via websocket API (`lovelace/resources/create`)
+- visionOS set as default theme via startup automation in `automations.yaml`
+
+### Dashboards
+
+Two custom Lovelace dashboards (not the default Overview):
+
+| Dashboard | URL Path | Columns | Optimized For |
+|-----------|----------|---------|---------------|
+| Mobile | `/dash-mobile` | 2 | Phone screens |
+| Desktop | `/dash-desktop` | 4 | Desktop/tablet |
+
+Both use **Sections** view type with **Mushroom Cards**. Created via HA websocket API (`lovelace/dashboards/create` + `lovelace/config/save`).
+
+**Sections on both dashboards:**
+
+1. **Header** — Title card + chips (weather, outside temp, vacuum status, phone battery)
+2. **Climate Control** — Living Room thermostat, Kitchen thermostat, Gree AC
+3. **Radiators** — Living Room, Main Bedroom, Girls Room
+4. **Temperatures** — 4 indoor Miaomiaoce BLE sensors + outside temp/humidity
+5. **Lights** — Living Room, Dining Room, Bedroom LED strip, Picture Frame lamp
+6. **Switches** — Entrance (x2), Bathroom (x2), Kids Bathroom (x2), Boys Lamp
+7. **Curtain & Vacuum** — Smart Curtain, Roborock S7, Vacuum battery
+
+### Startup Automation
+
+```yaml
+# /config/automations.yaml
+- id: set_visionos_theme
+  alias: "Set visionOS Theme on Startup"
+  trigger:
+    - platform: homeassistant
+      event: start
+  action:
+    - service: frontend.set_theme
+      data:
+        name: visionos
+```
+
+## Known Issues
+
+| Issue | Detail | Workaround |
+|-------|--------|------------|
+| Xiaomi devices on 192.168.31.x unreachable | Air purifiers, humidifier, Roborock on Xiaomi router subnet | Switch to cloud-only polling in xiaomi_miot config |
+| Cross-VLAN broadcast discovery | UDP broadcasts don't cross VLANs | Use manual IP config (e.g., `gree_manual` component) |
+| `/config/www/` not served after creation | HA needs full core restart to detect new `www` directory | `ha core restart` from HAOS VM |
+| `automations.yaml` syntax | Appending to `[]` creates invalid YAML | Always overwrite file, never append after `[]` |
+
+## Pending Work
+
+- [ ] Switch Xiaomi air purifiers/humidifier to cloud-only mode for reliable polling
+- [ ] Add more dashboard sections as new devices are added
+- [ ] Evaluate HACS frontend cards (mini-graph-card, apexcharts-card) for richer data display
+- [ ] Set up HA mobile app companion for phone notifications and presence detection
+
+## Technical Notes
+
+- **File transfer to HA:** base64 encode → virsh guest-exec → docker exec -i tee (chunk at 50KB for large files)
+- **HAOS minimal toolset:** Only `/usr/bin/curl`, `/sbin/ip` available — no wget/nc/python3/which
+- **Dashboard URL paths:** Must contain a hyphen (e.g., `dash-mobile`, not `mobile`)
+- **Lovelace resources:** Must be registered via websocket API, not by writing storage files directly
+- **HA API token:** Generated JWT with HMAC-SHA256 from refresh token's `jwt_key` in `/config/.storage/auth`

docs/wip/README.md

@@ -30,6 +30,12 @@ Planned changes, evaluations, and ideas not yet implemented.
 | [CONSOLE-PORT-ETHER5.md](CONSOLE-PORT-ETHER5.md) | EVALUATING | Low | Console/serial port on HAP1 ether5 |
 | [KVM-SWITCH-MAC-NOBARA.md](KVM-SWITCH-MAC-NOBARA.md) | EVALUATING | Medium | Software KVM for Mac/Nobara switching |
 
+### Smart Home
+
+| Document | Status | Priority | Description |
+|----------|--------|----------|-------------|
+| [HOME-ASSISTANT-SETUP.md](HOME-ASSISTANT-SETUP.md) | IN PROGRESS | High | HAOS VM, dashboards, themes, integrations |
+
 ### Applications
 
 | Document | Status | Priority | Description |