From aed577417c5d047262825fd8e868b74588ea0223 Mon Sep 17 00:00:00 2001
From: bardonadam <bardon.adam@gmail.com>
Date: Sat, 7 Feb 2026 10:47:17 +0100
Subject: [PATCH] docs: improve README examples and usage flow

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 76 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 1143ab3..962e1c2 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ Alternatively, install from source with:
 python -m pip install .
 ```
 
-## Usage
+## Setup
 
 ```python
 import os
@@ -29,25 +29,92 @@ from activitysmith import ActivitySmith
 activitysmith = ActivitySmith(
     api_key=os.environ["ACTIVITYSMITH_API_KEY"],
 )
+```
+
+## Usage
 
-# Push Notifications
-activitysmith.notifications.send(
+### Send a Push Notification
+
+```python
+response = activitysmith.notifications.send(
     {
-        # See PushNotificationRequest for fields
+        "title": "Build Failed",
+        "message": "CI pipeline failed on main branch",
     }
 )
 
-# Live Activities
-activitysmith.live_activities.start(
+print(response.success)
+print(response.devices_notified)
+```
+
+### Start a Live Activity
+
+```python
+start = activitysmith.live_activities.start(
     {
-        # See LiveActivityStartRequest for fields
+        "content_state": {
+            "title": "ActivitySmith API Deployment",
+            "subtitle": "start",
+            "number_of_steps": 4,
+            "current_step": 1,
+            "type": "segmented_progress",
+            "color": "yellow",
+        }
     }
 )
+
+activity_id = start.activity_id
 ```
 
-## API Surface
+### Update a Live Activity
+
+```python
+update = activitysmith.live_activities.update(
+    {
+        "activity_id": activity_id,
+        "content_state": {
+            "title": "ActivitySmith API Deployment",
+            "subtitle": "npm i & pm2",
+            "current_step": 3,
+        }
+    }
+)
+
+print(update.devices_notified)
+```
+
+### End a Live Activity
+
+```python
+end = activitysmith.live_activities.end(
+    {
+        "activity_id": activity_id,
+        "content_state": {
+            "title": "ActivitySmith API Deployment",
+            "subtitle": "done",
+            "current_step": 4,
+            "auto_dismiss_minutes": 3,
+        }
+    }
+)
+
+print(end.success)
+```
+
+## Error Handling
 
-The client exposes grouped resources:
+```python
+try:
+    activitysmith.notifications.send(
+        {
+            "title": "Build Failed",
+        }
+    )
+except Exception as err:
+    print("Request failed:", err)
+```
+
+## API Surface
 
 - `activitysmith.live_activities`
 - `activitysmith.notifications`