docs: complete beta 4 user guides

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -30,6 +30,16 @@ the GitHub release body should be rendered from the matching version section her
 - Replaced collector identifiers in newly tracked regression fixtures with
   synthetic allowlisted values so release privacy validation remains effective.
 
+### Docs
+
+- Added collector-first setup and runtime inverter-detection guides covering
+  discovery results, background discovery, Fast versus Full protocol checks,
+  polling, controls, UART management, and entity availability.
+- Updated device-learning, proxy-capture, remote-network, and Support Archive
+  instructions to match the current options flows and safety boundaries.
+- Added a plain-language legend to the generated inverter model catalog and
+  strengthened documentation checks for the current public workflows.
+
 ## [0.3.0-beta.3] - 2026-08-24
 
 ### Added

README.md

@@ -44,6 +44,10 @@ cloud. See the full, always-current list in the
 
 ## What it does
 
+- Finds collectors through a normal scan, an already connected session,
+  background discovery, or manual/remote setup.
+- Adds the verified collector first, then identifies the inverter safely on the
+  owned runtime connection.
 - Reads inverter, battery, PV, load, and grid data locally.
 - Creates normal Home Assistant sensors, numbers, selects, switches, and buttons.
 - Keeps the vendor app working alongside Home Assistant by default, or lets you
@@ -53,7 +57,11 @@ cloud. See the full, always-current list in the
   - **Read-only** — monitoring only.
   - **Auto** — enable verified controls when the device match is confident.
   - **Full Control** — expose available controls manually for advanced use.
-- Can create a **Support Archive** when your device needs diagnostics or new model support.
+- Can manage supported collector Wi-Fi, restart, UART, and connection settings.
+- Can collect read-only cloud evidence or verify extra controls for a partially
+  supported device.
+- Can create a **Support Archive**, run developer-provided diagnostic commands,
+  and capture collector traffic when normal diagnostics are not enough.
 - Works with the optional [EyeBond Local Card](https://github.com/groove-max/ha-eybond-local-card) dashboard.
 
 ---
@@ -125,6 +133,8 @@ It is a small ESP8266/ESP32-based bridge that connects directly to the inverter
 
 The setup wizard identifies and adds the collector first. After the entry is
 created, runtime detection identifies the inverter and creates its entities.
+For a complete explanation of scan results, address confirmation, background
+discovery, and manual setup, see [Setup and Discovery](docs/user/SETUP_AND_DISCOVERY.md).
 
 ### 1. Put the collector on the same network
 
@@ -217,6 +227,10 @@ stays high, increase the interval or switch back to Automatic.
 detecting an inverter, or only checking the collector, so long detection cycles
 are not confused with normal runtime polling.
 
+See [Runtime Detection and Entities](docs/user/RUNTIME_AND_INVERTER.md) for the
+driver selector, Fast versus Full protocol detection, multiple matches, control
+mode, and the difference between unavailable and disabled entities.
+
 ---
 
 ## Device learning
@@ -278,10 +292,10 @@ Use these issue templates:
 
 | Problem | Try this |
 |---|---|
-| Auto-scan finds nothing | Retry the scan or choose a different Home Assistant network interface. If needed, use advanced setup with the collector IP from your router. |
+| Auto-scan finds nothing | Retry the scan or choose a different Home Assistant network interface. If needed, follow [Setup and Discovery](docs/user/SETUP_AND_DISCOVERY.md) and use advanced setup with a known collector address. |
 | Bluetooth Wi-Fi setup is unavailable | Make sure Home Assistant has Bluetooth access near the collector. An ESPHome Bluetooth Proxy near the collector can help. |
 | Manual setup cannot verify the collector | Keep the setup flow open and retry with the collector reachable. For an inbound collector, enable background discovery and continue when its identified session appears. |
-| Only the collector device appears | Runtime detection has not identified the inverter yet. Wait for one detection cycle, then create a Support Archive if it remains unidentified. |
+| Only the collector device appears | Runtime detection has not identified the inverter yet. Check **Poll Context** and follow [Runtime Detection and Entities](docs/user/RUNTIME_AND_INVERTER.md); create a Support Archive if no driver binds. |
 | Sensors stay unavailable | Check that the collector and Home Assistant are on the same network and that the collector has stable Wi-Fi. |
 | Vendor app stopped showing live data | If you pointed the collector at Home Assistant only, that disconnects it from its cloud by design. Use **Restore previous collector endpoint** to bring the vendor app back. |
 | Vendor app works, but Home Assistant says unavailable | The collector may have reconnected to its cloud faster than it reconnected locally. Wait a few minutes and check Wi-Fi stability. |
@@ -295,6 +309,8 @@ Use these issue templates:
 ## Documentation
 
 - [Documentation index](docs/README.md)
+- [Setup and discovery](docs/user/SETUP_AND_DISCOVERY.md)
+- [Runtime detection and entities](docs/user/RUNTIME_AND_INVERTER.md)
 - [Collector management](docs/user/COLLECTOR_MANAGEMENT.md)
 - [Device learning](docs/user/DEVICE_LEARNING.md)
 - [Diagnostic commands](docs/user/DIAGNOSTIC_COMMANDS.md) — advanced, developer-directed scenarios

README.uk.md

@@ -44,6 +44,10 @@ SmartValue для Home Assistant, підключення EyeBond Wi-Fi-коле
 
 ## Що вміє інтеграція
 
+- Знаходить колектори звичайним пошуком, через уже відкрите з’єднання, фонове
+  виявлення або ручне/віддалене налаштування.
+- Спочатку додає перевірений колектор, а потім безпечно визначає інвертор через
+  належне цьому запису з’єднання.
 - Читає дані інвертора, батареї, PV, навантаження та мережі локально.
 - Створює звичайні сутності Home Assistant: сенсори, числа, списки вибору, перемикачі та кнопки.
 - За замовчуванням застосунок виробника працює разом із Home Assistant, або можна
@@ -53,7 +57,12 @@ SmartValue для Home Assistant, підключення EyeBond Wi-Fi-коле
   - **Лише читання** — тільки моніторинг.
   - **Автоматично** — перевірене керування вмикається саме.
   - **Повне керування** — ручне відкриття доступних елементів керування для досвідчених користувачів.
-- Може створити **архів підтримки**, якщо пристрій потребує діагностики або додавання підтримки.
+- На підтримуваних колекторах дозволяє змінювати Wi-Fi, перезапускати колектор,
+  налаштовувати UART і спосіб підключення.
+- Може зібрати хмарні дані лише для читання або перевірити додаткове керування
+  для частково підтримуваного пристрою.
+- Створює **архів підтримки**, виконує надані розробником діагностичні команди
+  та, за потреби, записує трафік колектора.
 - Працює з додатковою карткою [EyeBond Local Card](https://github.com/groove-max/ha-eybond-local-card).
 
 ---
@@ -128,6 +137,8 @@ PI30 та SRNE. Рівень підтримки залежить від моде
 Майстер налаштування ідентифікує та додає колектор. Після створення запису
 інтеграція визначає інвертор через належну цьому запису сесію та створює його
 сутності.
+Повний опис результатів пошуку, підтвердження адреси, фонового виявлення та
+ручного налаштування: [Налаштування та пошук](docs/user/SETUP_AND_DISCOVERY.md).
 
 ### 1. Підключіть колектор до тієї самої мережі
 
@@ -223,6 +234,10 @@ Modbus-пристрої можуть оновлюватися частіше, н
 лише перевіряє колектор, щоб довгі цикли пошуку не плуталися зі звичайним
 опитуванням під час роботи.
 
+Вибір драйвера, швидкий і повний пошук протоколу, кілька знайдених протоколів,
+режими керування та різницю між недоступними й вимкненими сутностями пояснено в
+[Визначення інвертора та сутності](docs/user/RUNTIME_AND_INVERTER.md).
+
 ---
 
 ## Навчання пристрою
@@ -287,10 +302,10 @@ Modbus-пристрої можуть оновлюватися частіше, н
 
 | Проблема | Що спробувати |
 |---|---|
-| Автопошук нічого не знаходить | Повторіть пошук або виберіть інший мережевий інтерфейс Home Assistant. За потреби використайте розширене налаштування з IP колектора з роутера. |
+| Автопошук нічого не знаходить | Повторіть пошук або виберіть інший мережевий інтерфейс Home Assistant. За потреби відкрийте [Налаштування та пошук](docs/user/SETUP_AND_DISCOVERY.md) і введіть відому адресу колектора. |
 | Bluetooth Wi-Fi недоступний | Переконайтеся, що Home Assistant має Bluetooth поруч із колектором. Може допомогти ESPHome Bluetooth Proxy біля колектора. |
 | Ручне налаштування не може підтвердити пристрій | Не закривайте майстер і повторіть спробу, коли пристрій доступний. Для вхідного підключення увімкніть фонове виявлення й продовжте, коли з’явиться ідентифікована сесія. |
-| З’явився лише пристрій колектора | Визначення інвертора ще не завершилося. Зачекайте один цикл визначення; якщо інвертор не з’явиться, створіть архів підтримки. |
+| З’явився лише пристрій колектора | Визначення інвертора ще не завершилося. Перевірте **Poll Context** і відкрийте [Визначення інвертора та сутності](docs/user/RUNTIME_AND_INVERTER.md); якщо драйвер не визначиться, створіть архів підтримки. |
 | Сенсори недоступні | Перевірте, що колектор і Home Assistant у тій самій мережі, а Wi-Fi колектора стабільний. |
 | Застосунок виробника перестав показувати дані | Якщо ви спрямували колектор лише на Home Assistant, це навмисно відключає його від хмари. Скористайтеся дією **Відновити попередню адресу колектора**, щоб повернути застосунок виробника. |
 | Застосунок виробника працює, а Home Assistant показує недоступність | Колектор міг швидше відновити зв'язок із хмарою, ніж локально з Home Assistant. Зачекайте кілька хвилин і перевірте Wi-Fi. |
@@ -304,6 +319,8 @@ Modbus-пристрої можуть оновлюватися частіше, н
 ## Документація
 
 - [Покажчик документації](docs/README.md)
+- [Налаштування та пошук](docs/user/SETUP_AND_DISCOVERY.md)
+- [Визначення інвертора та сутності](docs/user/RUNTIME_AND_INVERTER.md)
 - [Керування колектором](docs/user/COLLECTOR_MANAGEMENT.md)
 - [Навчання пристрою](docs/user/DEVICE_LEARNING.md)
 - [Діагностичні команди](docs/user/DIAGNOSTIC_COMMANDS.md) — розширені сценарії від розробника

docs/README.md

@@ -8,7 +8,9 @@ release work; they are not required to use the integration.
 ## User guides
 
 - [Main README](../README.md) — installation, setup, connection settings, troubleshooting, and support flow
-- [Collector Management](user/COLLECTOR_MANAGEMENT.md) — how the collector connects, runtime settings, Wi-Fi change, restart, and proxy capture basics
+- [Setup and Discovery](user/SETUP_AND_DISCOVERY.md) — collector-first setup, scan results, address confirmation, background discovery, and manual setup
+- [Runtime Detection and Entities](user/RUNTIME_AND_INVERTER.md) — driver detection, Fast and Full protocol checks, polling, controls, and entity availability
+- [Collector Management](user/COLLECTOR_MANAGEMENT.md) — cloud connection profiles, Wi-Fi, restart, UART, virtual bridges, and proxy-capture basics
 - [Device Learning](user/DEVICE_LEARNING.md) — read-only cloud evidence and active verification of extra sensors and controls
 - [Diagnostic Commands](user/DIAGNOSTIC_COMMANDS.md) — advanced, developer-provided read/write scenarios and shareable results
 - [Support Archive](user/SUPPORT_ARCHIVE.md) — what to attach when asking for hardware support

docs/generated/INVERTER_MODEL_CATALOG.generated.md

@@ -6,6 +6,17 @@ Generated by `tools/model_catalog.py`. Do not edit by hand.
 - Runtime inverter catalog version: 2026.08.4
 - Models: 16 | Variants: 17
 
+## How To Read This Catalog
+
+This page describes what has been confirmed for a specific inverter model or model family. It is more precise than a simple compatibility list.
+
+- **Supported Models** have a safe built-in runtime path and confirmed telemetry.
+- **Limited Or Experimental Models** can still work, but a listed limitation, partial telemetry, unconfirmed controls, or a read-only path remains.
+- **Research Queue** records known hardware that does not yet have a safe built-in runtime path.
+- **Telemetry** describes confidence in local readings; **Controls** describes confidence in local writes; **Hardware** describes the evidence available from a real device.
+- **Protocol**, **Detection**, **Runtime Tier**, descriptors, surfaces, and fingerprints are implementation details useful when comparing variants.
+- **Family-level runtime coverage** means EyeBond Local has a safe generic protocol path, but has not claimed an exact commercial model identity.
+
 ## Supported Models
 
 | Manufacturer | Model | Protocol | Detection | Runtime Tier | Telemetry | Controls | Hardware |

docs/user/COLLECTOR_MANAGEMENT.md

@@ -27,7 +27,14 @@ The collector access point name usually contains the collector identifier. Some
 
 After the device is added, you can change the collector Wi-Fi from the collector device page.
 
-If you change the collector network and it receives a new IP address, removing and adding the integration again can be the simplest way to pick up the new address cleanly.
+If you change the collector network and it receives a new IP address, keep the
+existing entry. Wait for the collector to reconnect, then reload the entry if
+needed. If it stays offline, run normal or background discovery so EyeBond Local
+can observe the same collector identity on its new route. Removing the entry is
+a last resort because it also removes the established device relationship.
+
+For initial setup, scan result meanings, and background discovery, see
+[Setup and Discovery](SETUP_AND_DISCOVERY.md).
 
 ## Collector connection and cloud
 
@@ -120,7 +127,9 @@ Use this when the collector must join a different SSID or when you are moving it
 - apply the new settings
 - expect the collector to reconnect, sometimes on a new IP address
 
-After a Wi-Fi change, re-adding the device can be the easiest way to pick up the new collector IP cleanly.
+Keep the existing entry after a Wi-Fi change. The collector identity, not its
+old IP address, is the durable device key. Wait for reconnect and reload the
+entry; use discovery only if the new route is not observed automatically.
 
 <p align="center"><img src="../images/collector-wifi-settings.png" alt="Change collector Wi-Fi dialog" width="480"></p>
 
@@ -134,6 +143,27 @@ that exact active connection. Setup and connection-recovery flows additionally
 wait for the collector to disconnect and reconnect with the same identity before
 accepting the operation as a successful recovery.
 
+If the restart button is unavailable, the current session has not negotiated a
+management adapter that can safely send the command. This is a capability
+decision for the live session, not a guess based on the collector model.
+
+### Change inverter UART speed
+
+This option appears only when the collector exposes UART management. It changes
+the collector-to-inverter baud rate; it does not change the Home Assistant TCP
+listener or Wi-Fi settings.
+
+- Use **Refresh UART status** to read the current setting.
+- Use **Save UART speed** only when you know the inverter's required baud rate.
+- PI30/Voltronic devices commonly use `2400`; SMG/Modbus devices commonly use
+  `9600`, but the exact inverter documentation is authoritative.
+- A wrong speed can leave the collector online while all inverter entities
+  become unavailable. Return to this screen and restore the previous speed.
+
+ESP EyeBond Collector exposes this action when its platform supports runtime
+UART changes. BK72xx/LibreTiny builds require changing `baud_rate:` in the
+ESPHome YAML and reflashing instead; the options screen reports that limitation.
+
 ### Capture collector traffic
 
 This is a support tool. Most users do not need it for normal operation.
@@ -187,6 +217,9 @@ If Home Assistant and the collector are on the same LAN, you usually do not need
 
 If the collector is remote, behind another router, or must call back through VPN or port forwarding, read the [Remote / NAT Setup Guide](REMOTE_SETUP.md).
 
+For driver detection, Fast versus Full protocol checks, polling, controls, and
+disabled entities, see [Runtime Detection and Entities](RUNTIME_AND_INVERTER.md).
+
 ## Need help?
 
 If something still does not look right: