docs(readme): trim duplicated examples, surface docs site (#2101)

## Summary

Trims the main README so it leans on the documentation site rather than
duplicating tutorial content.

- Replaces the two large Cloud + Local API code blocks (~95 lines) with
a single short cloud snippet showing the shape of the library, plus a
link to the Getting started guide for commands, events, and the local
API.
- Adds a **Documentation** section near the top with direct links to the
high-value docs pages (getting started, core concepts, device control,
event handling, migration, SDK reference).
- Keeps the intro, supported hubs, installation, projects-using, and
contribute sections unchanged.

## Why

The duplicated examples drifted easily (especially across the v2 API
renames) and made up over half the README. The docs site is versioned
alongside the code, so it's the better home for tutorial-depth content.
Net change: -76 / +15 lines.

Author: iMicknl

README.md

@@ -2,7 +2,17 @@
 
 A fully asynchronous and user-friendly API client for the OverKiz platform. This client enables interaction with smart devices connected to OverKiz, supporting multiple vendors such as Somfy TaHoma and Atlantic Cozytouch.
 
-This package is primarily used by Home Assistant Core to provide the Overkiz integration. If you wish to use this package in your own project, refer to the [full documentation](https://imicknl.github.io/python-overkiz-api/), the [examples below](#getting-started), or explore the [Home Assistant source code](https://github.com/home-assistant/core/tree/dev/homeassistant/components/overkiz) for additional usage examples.
+This package is primarily used by Home Assistant Core to provide the Overkiz integration. If you wish to use this package in your own project, refer to the [full documentation](https://imicknl.github.io/python-overkiz-api/), the [example below](#getting-started), or explore the [Home Assistant source code](https://github.com/home-assistant/core/tree/dev/homeassistant/components/overkiz) for additional usage examples.
+
+## Documentation
+
+Full documentation is available at **[imicknl.github.io/python-overkiz-api](https://imicknl.github.io/python-overkiz-api/)**:
+
+- [Getting started](https://imicknl.github.io/python-overkiz-api/getting-started/) — cloud and local API setup
+- [Core concepts](https://imicknl.github.io/python-overkiz-api/core-concepts/) — clients, servers, credentials, and models
+- [Device control](https://imicknl.github.io/python-overkiz-api/device-control/) and [event handling](https://imicknl.github.io/python-overkiz-api/event-handling/)
+- [Migrating from v1](https://imicknl.github.io/python-overkiz-api/migration-v2/)
+- [SDK reference](https://imicknl.github.io/python-overkiz-api/sdk-reference/)
 
 ## Supported hubs
 
@@ -11,7 +21,7 @@ This package is primarily used by Home Assistant Core to provide the Overkiz int
 - Brandt Smart Control **\***
 - Hitachi Hi Kumo
 - Nexity Eugénie
-- Rexel Energeasy Connect **\***
+- Rexel Energeasy Connect **\*\***
 - Sauter Cozytouch
 - Simu (LiveIn2)
 - Somfy Connexoon IO
@@ -20,7 +30,8 @@ This package is primarily used by Home Assistant Core to provide the Overkiz int
 - Somfy TaHoma Switch
 - Thermor Cozytouch
 
-\[*] _These servers utilize an authentication method that is currently not supported by this library. To use this library with these servers, you will need to obtain an access token (by sniffing the original app) and create a local user on the Overkiz API platform._
+\[*] _This server's authentication method isn't supported yet. To use it, obtain an access token (by sniffing the original app) and create a local user on the Overkiz API platform._
+\[**] _Requires OAuth credentials provided by Rexel._
 
 ## Installation
 
@@ -30,103 +41,32 @@ pip install pyoverkiz
 
 ## Getting started
 
-
-### Cloud API
+Connect to the cloud API, authenticate, and list your devices:
 
 ```python
 import asyncio
 
 from pyoverkiz.auth.credentials import UsernamePasswordCredentials
 from pyoverkiz.client import OverkizClient
-from pyoverkiz.models import Action, Command
-from pyoverkiz.enums import Server, OverkizCommand
-
-USERNAME = ""
-PASSWORD = ""
+from pyoverkiz.enums import Server
 
 
 async def main() -> None:
     async with OverkizClient(
         server=Server.SOMFY_EUROPE,
-        credentials=UsernamePasswordCredentials(USERNAME, PASSWORD),
+        credentials=UsernamePasswordCredentials("username", "password"),
     ) as client:
         await client.login()
 
         devices = await client.get_devices()
-
         for device in devices:
             print(f"{device.label} ({device.device_url}) - {device.controllable_name}")
-            print(f"{device.widget} - {device.ui_class}")
-
-        await client.execute_action_group(
-            actions=[
-                Action(
-                    device_url="io://1234-5678-1234/12345678",
-                    commands=[
-                        Command(name=OverkizCommand.SET_CLOSURE, parameters=[100])
-                    ]
-                )
-            ],
-            label="Execution via Python",
-            # mode=ExecutionMode.HIGH_PRIORITY
-        )
-
-        while True:
-            events = await client.fetch_events()
-            print(events)
-
-            await asyncio.sleep(2)
 
 
 asyncio.run(main())
 ```
 
-### Local API
-
-```python
-import asyncio
-
-from pyoverkiz.auth.credentials import LocalTokenCredentials
-from pyoverkiz.client import OverkizClient
-from pyoverkiz.utils import create_local_server_config
-
-LOCAL_GATEWAY = "gateway-xxxx-xxxx-xxxx.local"  # or use the IP address of your gateway
-VERIFY_SSL = True  # set verify_ssl to False if you don't use the .local hostname
-
-
-async def main() -> None:
-    token = ""  # generate your token via the Somfy app and include it here
-
-    async with OverkizClient(
-        server=create_local_server_config(host=LOCAL_GATEWAY),
-        credentials=LocalTokenCredentials(token),
-        verify_ssl=VERIFY_SSL,
-    ) as client:
-        await client.login()
-
-        print("Local API connection successful!")
-
-        print(await client.get_api_version())
-
-        setup = await client.get_setup()
-        print(setup)
-
-        devices = await client.get_devices()
-        print(devices)
-
-        for device in devices:
-            print(f"{device.label} ({device.device_url}) - {device.controllable_name}")
-            print(f"{device.widget} - {device.ui_class}")
-
-        while True:
-            events = await client.fetch_events()
-            print(events)
-
-            await asyncio.sleep(2)
-
-
-asyncio.run(main())
-```
+For executing commands, listening to events, and connecting to the **local API**, see the [Getting started guide](https://imicknl.github.io/python-overkiz-api/getting-started/) in the documentation.
 
 ## Projects using pyOverkiz
 

docs/getting-started.md

@@ -2,7 +2,7 @@
 
 This guide will help you install the library, connect to your hub, and perform your first actions.
 
-> Need the official Overkiz cloud API reference? Visit the [Overkiz API Documentation](https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/doc) ([mirror](/api)). Most endpoints are accessible via the pyOverkiz package.
+> Need the official Overkiz cloud API reference? Visit the [Overkiz API Documentation](https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/doc) ([mirror](api/index.html)). Most endpoints are accessible via the pyOverkiz package.
 
 > Upgrading from pyOverkiz 1.x? See the [migration guide](migration-v2.md) for a full list of breaking changes.
 
@@ -178,6 +178,10 @@ Use a cloud server when you want to connect through the vendor’s public API. U
     https://my.home-assistant.io/redirect/oauth?code=AUTHORIZATION_CODE&state=STATE_VALUE
     ```
 
+    Compare the returned `state` against the value from step 1 before
+    continuing, and reject the response if they differ — this is what guards
+    against CSRF.
+
     **Step 3: Exchange authorization code for access token**
 
     ```python
@@ -187,7 +191,11 @@ Use a cloud server when you want to connect through the vendor’s public API. U
     from pyoverkiz.enums import Server
     from pyoverkiz.const import REXEL_OAUTH_REDIRECT_URI
 
-    async def main() -> None:
+    async def main(returned_state: str) -> None:
+        # Verify the state echoed back by the redirect matches step 1.
+        if returned_state != state:
+            raise ValueError("State mismatch — possible CSRF, aborting.")
+
         # Use the authorization code from the redirect
         async with OverkizClient(
             server=Server.REXEL,
@@ -197,10 +205,16 @@ Use a cloud server when you want to connect through the vendor’s public API. U
                 code_verifier=code_verifier,  # From step 1
             ),
         ) as client:
-            await client.login()
+            await client.login()  # auto-selects a sole gateway
+
+            # Accounts with more than one gateway must select one explicitly.
+            gateways = await client.discover_gateways()
+            if len(gateways) > 1:
+                client.select_gateway(gateways[0].gateway_id)
+
             # Client is now authenticated and ready to use
 
-    asyncio.run(main())
+    asyncio.run(main(returned_state="STATE_VALUE_FROM_REDIRECT"))
     ```
 
 === "Rexel (externally-managed token)"

docs/index.md

@@ -24,16 +24,17 @@ pyOverkiz is an async Python library for interacting with Overkiz-based platform
 
 - Atlantic Cozytouch
 - Bouygues Flexom
+- Brandt Smart Control **\***
 - Hitachi Hi Kumo
 - Nexity Eugénie
+- Rexel Energeasy Connect **\*\***
 - Sauter Cozytouch
 - Simu (LiveIn2)
 - Somfy Connexoon IO
 - Somfy Connexoon RTS
 - Somfy TaHoma
 - Somfy TaHoma Switch
 - Thermor Cozytouch
-- Brandt Smart Control **\***
-- Rexel Energeasy Connect **\***
 
-\[*] _These servers utilize an authentication method that is currently not supported by this library._
+\[*] _This server's authentication method isn't supported yet. To use it, obtain an access token (by sniffing the original app) and create a local user on the Overkiz API platform._
+\[**] _Requires OAuth credentials provided by Rexel._

docs/troubleshooting.md

@@ -6,6 +6,15 @@
 - Re-run `login()` and retry the call.
 - On `NotAuthenticatedError`, re-authenticate before retrying.
 
+## Rexel (Energeasy Connect)
+
+Rexel authenticates with OAuth2 and scopes every request to a single gateway, so its failure modes differ from username/password servers.
+
+- `InvalidTokenError: Consent is missing or revoked for Rexel token.` — the access token does not carry the consent Rexel requires. Re-run the OAuth2 authorization flow so the user grants consent again.
+- `InvalidTokenError: Error retrieving Rexel access token: ...` — the code exchange or refresh failed (expired authorization code, reused code, or invalid `code_verifier`). Restart the flow from a freshly generated PKCE pair.
+- `NoGatewaySelectedError: Multiple Rexel gateways available; call discover_gateways() ...` — the account has more than one gateway and none is selected. Call `discover_gateways()` and pass one id to `select_gateway()` before making device calls. A single-gateway account is auto-selected on `login()`.
+- `AccessDeniedToGatewayError` — the selected `gateway_id` is not reachable for this token. Re-discover gateways and select a valid one; if you persisted a `gateway_id`, confirm it still belongs to the account.
+
 ## Rate limits and concurrency
 
 - Reduce polling frequency.
@@ -54,6 +63,8 @@ asyncio.run(fetch_devices_with_retry())
 - `TooManyExecutionsError`
 - `MaintenanceError`
 - `AccessDeniedToGatewayError`
+- `NoGatewaySelectedError`
+- `InvalidTokenError`
 
 ## SSL and local certificates