From 3091d026facf74b1a4960f8e6ef8c7d5a73912e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A6rkeren?=
 <164513459+Faerkeren@users.noreply.github.com>
Date: Wed, 27 May 2026 19:22:22 -0100
Subject: [PATCH] docs: expose public package surface in API overview

The reference overview rendered the top-level haclient package with
show_submodules: false and members: false, hiding the public import
contract defined by haclient.__init__.__all__.

Add a hand-written table mapping every name in __all__ to its reference
page so users get a clear, discoverable overview of HAClient,
SyncHAClient, ConnectionConfig, DomainSpec, Entity, the exception
types, and the rest of the public surface.

Refs #94
---
 docs/reference/index.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/reference/index.md b/docs/reference/index.md
index 600066a..f890815 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -1,5 +1,41 @@
 # API Reference
 
+The `haclient` package re-exports its public API at the top level. The
+table below maps every name in `haclient.__all__` to the reference page
+where it is documented.
+
+## Public exports
+
+| Name | Kind | Reference |
+| --- | --- | --- |
+| `HAClient` | Async client facade | [HAClient (facade)](api.md) |
+| `SyncHAClient` | Blocking wrapper | [Sync Client](sync.md) |
+| `ConnectionConfig` | Configuration | [Configuration](config.md) |
+| `ServicePolicy` | Configuration | [Configuration](config.md) |
+| `Entity` | Entity base class | [Entity](entity.md) |
+| `Connection` | Core | [Connection](core/connection.md) |
+| `EventBus` | Core | [Event Bus](core/events.md) |
+| `ServiceCaller` | Core | [Service Caller](core/services.md) |
+| `StateStore` | Core | [State Store](core/state.md) |
+| `EntityRegistry` | Core | [Entity Registry](core/registry.md) |
+| `EntityFactory` | Core | [Entity Factory](core/factory.md) |
+| `DomainAccessor` | Plugins | [Plugins](core/plugins.md) |
+| `DomainRegistry` | Plugins | [Plugins](core/plugins.md) |
+| `DomainSpec` | Plugins | [Plugins](core/plugins.md) |
+| `register_domain` | Plugins | [Plugins](core/plugins.md) |
+| `Clock` | Port protocol | [Ports](ports.md) |
+| `RestPort` | Port protocol | [Ports](ports.md) |
+| `WebSocketPort` | Port protocol | [Ports](ports.md) |
+| `HAClientError` | Exception | [Exceptions](exceptions.md) |
+| `AuthenticationError` | Exception | [Exceptions](exceptions.md) |
+| `CommandError` | Exception | [Exceptions](exceptions.md) |
+| `ConnectionClosedError` | Exception | [Exceptions](exceptions.md) |
+| `EntityNotFoundError` | Exception | [Exceptions](exceptions.md) |
+| `HTTPError` | Exception | [Exceptions](exceptions.md) |
+| `TimeoutError` | Exception | [Exceptions](exceptions.md) |
+
+## Package
+
 ::: haclient
     options:
       show_submodules: false