docs: add runtime feature overview

Summarize the runtime client, workspace, retry, result, and health helpers so downstream adapters can quickly understand the package surface.

Author: eddietejeda

README.md

@@ -4,6 +4,17 @@ Shared runtime primitives for Hotdata integrations: workspace/session semantics,
 
 Runtime boundary and guarantees are defined in `CONTRACT.md`.
 
+## Features
+
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, `HOTDATA_WORKSPACE`, and `HOTDATA_SANDBOX`.
+- **Workspace resolution** — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
+- **Sandbox/session propagation** — pass sandbox session context through the SDK via `X-Session-Id`.
+- **HTTP resilience** — configure SDK retries for transient connection failures and retry SQL execution on stale pooled sockets.
+- **SQL execution helper** — run SQL through `POST /v1/query`, poll async query runs when needed, and return a `QueryResult`.
+- **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.
+- **History helpers** — list recent results and query run history with normalized dataclasses.
+- **Health helpers** — build compact API/workspace health summaries for UI integrations.
+
 Install:
 
 ```bash