From f576a45d8f6f69326af789fbf7d95213f67d2fc9 Mon Sep 17 00:00:00 2001
From: "Jan-Peter v. Hunnius" <jan@hunnius.net>
Date: Wed, 24 Jun 2026 10:21:38 +0200
Subject: [PATCH] docs: add car_grip use case and grip analysis response format
 to README

---
 README.md | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 4cb789e..d9913fe 100644
--- a/README.md
+++ b/README.md
@@ -201,8 +201,7 @@ A built-in HTTP API server runs on port 8080 for recording management and live t
 | POST | `/api/recordings/{id}/stop` | Stop specific recording |
 | DELETE | `/api/recordings/{id}` | Delete recording |
 | GET | `/api/recordings/{id}/data/{feed_name}` | Download raw feed JSONL |
-| GET | `/api/use-cases` | List valid use cases |
-| GET | `/api/games` | List supported games |
+| GET | `/api/use-cases` | List valid use cases || GET | `/api/games` | List supported games |
 | GET | `/api/sessions` | List all sessions |
 | POST | `/api/sessions` | Create analysis session |
 | GET | `/api/sessions/{id}` | Get session details |
@@ -302,6 +301,7 @@ Returns the updated session on success.
 ```json
 [
   { "id": "shift_points", "name": "ShiftPoints", "guidance": "1. Drive to a long straight..." },
+  { "id": "car_grip", "name": "CarGrip", "guidance": "Drive 3-5 laps at race pace..." },
   { "id": "track_mapping", "name": "TrackMapping", "guidance": "1. Drive a complete lap..." }
 ]
 ```
@@ -346,6 +346,35 @@ The characteristics endpoints aggregate shift-point analysis data across all com
 }
 ```
 
+### Car Grip Analysis Response
+
+Produced by the `car_grip` use case. The analysis uses **envelope extraction** — for each 10 km/h speed bin, it finds the peak |lateral G|, peak acceleration G, and peak braking G. This builds the grip limit curve from whatever data you provide; the harder you drive, the more complete the profile.
+
+```json
+{
+  "summary": {
+    "max_lateral_g": 1.42,
+    "max_accel_g": 0.85,
+    "max_brake_g": 1.35,
+    "max_combined_g": 1.58,
+    "peak_lateral_speed_kmh": 120.0
+  },
+  "grip_envelope": [
+    { "speed_kmh": 45.0, "max_lateral_g": 1.2, "max_accel_g": 0.8, "max_brake_g": 1.1, "sample_count": 340 }
+  ],
+  "grip_circle": [
+    { "longitudinal_g": 0.5, "lateral_g": -1.2 }
+  ],
+  "steering_response": [
+    { "steer": 0.15, "lateral_g": -1.1, "speed_kmh": 95.0 }
+  ],
+  "runs_analyzed": 3,
+  "total_frames_analyzed": 8400
+}
+```
+
+The `grip_envelope` array has one entry per populated speed bin. The `grip_circle` and `steering_response` arrays are downsampled scatter points (~800 each) for chart rendering.
+
 ### Shift Point Analysis Response
 
 ```json