ha(H5): README+HACS, скрипт приёмки, релизный чек-лист

- custom_components/fglair/README.md: HACS-установка, cloud/ручной/импорт,
  превью шаблона, сущности, ключ для ESPHome (reconfigure/CLI), диагностика
  и troubleshoot; заглушки screenshots/step-1..8.png (сгенерированы)
- tests/acceptance/test_esphome_ha.py: quick/burst/long через REST API HA
  (long-lived token), адаптивная матрица по capabilities, возврат исходного
  состояния, CSV-отчёт long, опциональный ESPHome-канал (aioesphomeapi)
- self-test приёмки на моке HA REST (6 тестов, без железа)
- hacs.json; README: раздел Home Assistant; docs/RELEASE_HA.md: публикация
  pyfglair на PyPI (wheel/sdist, auditwheel), HACS-релиз, приёмка
- scripts/py-ci.sh: tests/acceptance; план H5 отмечен

custom_components/fglair/README.md

@@ -0,0 +1,134 @@
+# FGLair — интеграция Home Assistant
+
+Локальное управление кондиционерами Fujitsu General (FGLair / Ayla LAN)
+без облака в рантайме. Вся протокольная логика — в C++-ядре
+[`fgl-aircon`](../../README.md) через python-пакет `pyfglair` (cffi).
+
+> Скриншоты `screenshots/step-N.png` — заглушки-плейсхолдеры: владелец
+> заменит их реальными снимками, описания «что должно быть видно» даны
+> рядом с каждым шагом.
+
+## Требования
+
+* Home Assistant ≥ 2025.1 (Linux x86_64/aarch64).
+* Пакет `pyfglair` (манифест ставит его автоматически из PyPI).
+  До публикации на PyPI установите wheel вручную в python-окружение HA:
+  `pip install pyfglair-*.whl` (см. `docs/RELEASE_HA.md`).
+* Модуль кондиционера в той же LAN. Модуль поддерживает **2 LAN-сессии**:
+  телефон с FGLair и HA уживаются; третья (например, ESPHome) получит 503.
+
+## Установка через HACS
+
+1. HACS → ⋮ → **Custom repositories** → URL репозитория, категория
+   **Integration** → **Add**.
+
+   ![шаг 1](screenshots/step-1.png)
+
+   *Должно быть видно: диалог добавления custom repository с заполненным URL
+   и выбранной категорией Integration.*
+
+2. Найдите **FGLair** в HACS → **Download** → перезапустите Home Assistant.
+
+   ![шаг 2](screenshots/step-2.png)
+
+   *Должно быть видно: страница загрузки интеграции с кнопкой Download и
+   версией.*
+
+## Добавление устройства
+
+3. Settings → Devices & Services → **Add Integration** → «FGLair».
+
+   ![шаг 3](screenshots/step-3.png)
+
+   *Должно быть видно: диалог поиска интеграции с введённым «FGLair» и
+   выделенным результатом.*
+
+4. **Вход в облако** (шаг 1A): e-mail/пароль FGLair и регион. Облако
+   используется один раз — получить статический LAN-ключ модуля.
+
+   ![шаг 4](screenshots/step-4.png)
+
+   *Должно быть видно: форма с заполненными регионом EU и e-mail, пароль
+   скрыт.*
+
+5. **Выбор устройства**: список найденных кондиционеров (имя, модель, IP).
+
+   ![шаг 5](screenshots/step-5.png)
+
+   *Должно быть видно: список с одним устройством (имя, модель, host).*
+
+6. **Проверка шаблона с превью** (шаг 3): форма-предпросмотр рассчитанных
+   значений (режимы, диапазон температур, пример конверсии) и, при
+   необходимости, ручные коэффициенты/диапазон уставки. Сверьте с
+   приложением FGLair и подтвердите.
+
+   ![шаг 6](screenshots/step-6.png)
+
+   *Должно быть видно: таблица превью — режимы, диапазон 16–30 °C, шаг,
+   текущая температура, capabilities, кнопки Submit.*
+
+7. **Готово**: карточка устройства с сущностями climate/switch/select/
+   sensor/binary_sensor.
+
+   ![шаг 7](screenshots/step-7.png)
+
+   *Должно быть видно: страница устройства с созданными сущностями.*
+
+## Где взять ключ для ESPHome
+
+Download diagnostics на странице устройства показывает `dsn`,
+`lanip_key_id`, `host` и **маску** ключа. Полный ключ (для
+`secrets.yaml` ESPHome) получите явным действием:
+
+* **Настроить заново** (Reconfigure) на карточке интеграции — вход в
+  облако FGLair покажет/сохранит актуальный ключ; либо
+* `python -m pyfglair discover --region eu --email you@example.com
+  --format esphome-secrets` на хосте HA.
+
+   ![шаг 8](screenshots/step-8.png)
+
+   *Должно быть видно: страница Diagnostics с полями dsn/lanip_key_id/host
+   и маской lanip_key.*
+
+Альтернатива без облака — ручной ввод параметров (host, dsn, lanip_key,
+lanip_key_id) или импорт `config_*.json` от `fglair-discover`/`fglctl`.
+
+## Сущности
+
+| Платформа | Что создаётся |
+|---|---|
+| climate | режим (off/cool/dry/fan/heat/auto), скорость, swing (верт./гориз.), preset ECO/BOOST, уставка, текущая температура |
+| switch | economy, powerful, coil dry, min heat, outdoor low noise, human det auto save, Wi-Fi LED, indoor fan control (по шаблону и capabilities) |
+| select | положение вертикальной/горизонтальной заслонки (0…N−1) |
+| sensor | температура в помещении, код ошибки, диагностическое состояние связи |
+| binary_sensor | connectivity + флаги op_status (defrost, maintenance, oil recovery, pump down, check operation, …) |
+
+Список зависит от шаблона устройства (A/B/F) и маски `device_capabilities`;
+режимы, которыми прибор не управляет, не создаются.
+
+## Диагностика и известные ситуации
+
+* **503 / оба слота заняты** — в LAN уже две сессии (телефон + ESPHome).
+  Освободите один слот и перезапустите интеграцию.
+* **key_error** — LAN-ключ не совпал (`key_id` изменился). В HA появится
+  Repair; нажмите **Настроить заново** и повторите вход в облако (или
+  вставьте новый `config_*.json`).
+* **unavailable** — модуль недоступен (сеть/питание) или нет слотов;
+  диагностический сенсор «Состояние связи» показывает детали
+  (idle/registering/online/recovering/offline/key_error).
+* Записи не эхо-подтверждаются модулем: состояние обновляется
+  оптимистично и подтверждается push-обновлением.
+
+## Приёмка на живом стенде
+
+`tests/acceptance/test_esphome_ha.py` (stdlib) прогоняет матрицу изменений
+через REST API HA по long-lived token, с возвратом к исходному состоянию:
+
+```sh
+python tests/acceptance/test_esphome_ha.py quick \
+    --ha-url http://homeassistant.local:8123 --ha-token TOKEN \
+    --entity climate.ac
+python tests/acceptance/test_esphome_ha.py long \
+    --ha-url ... --ha-token ... --entity climate.ac \
+    --hours 24 --interval 3600 --report acceptance.csv
+```