docs: update README.md and project plan for session management and analysis

README.md

@@ -1,8 +1,8 @@
 # rusty-telemetry
 
-Multi-port UDP telemetry listener for sim racing games, with a terminal UI.
+Multi-port UDP telemetry listener and analysis platform for sim racing games.
 
-Receives real-time telemetry from **Assetto Corsa** and **Project CARS 1 & 2** via UDP, parses binary packet formats, and displays live data in a terminal dashboard built with ratatui.
+Receives real-time telemetry from **Assetto Corsa** and **Project CARS 1 & 2** via UDP, parses binary packet formats, and provides live data via a terminal dashboard and REST API. Supports use-case driven analysis sessions for shift point optimization and track mapping.
 
 ## Supported Games
 
@@ -33,6 +33,7 @@ Press **q** or **Ctrl+C** to quit.
 | `RUSTY_TELEMETRY_LISTEN` | Local address to bind for incoming UDP feeds (Telemetry Tool, PCARS) | `0.0.0.0` |
 | `RUSTY_TELEMETRY_BIND` | Fallback for both of the above (backward compatibility) | — |
 | `RUSTY_TELEMETRY_API_PORT` | REST API server port | `8080` |
+| `RUSTY_TELEMETRY_API_HOST` | REST API server bind address | `127.0.0.1` |
 
 ### Same Machine
 
@@ -129,7 +130,7 @@ Each panel shows:
 
 ## Data Capture
 
-A recording is auto-started on launch. All raw UDP packets are written to per-feed JSONL files under a UUID-based directory:
+All feeds are continuously recorded into in-memory ring buffers (5 minutes, 18,000 frames per feed). A recording is auto-started on launch; on shutdown, ring buffer contents are flushed to per-feed JSONL files:
 
 ```
 ./data/<uuid>/
@@ -139,7 +140,18 @@ A recording is auto-started on launch. All raw UDP packets are written to per-fe
 └── feed_5606_pcars.jsonl
 ```
 
-Each recording contains a `manifest.json` with metadata (game, track, car, use case, status, timestamps) and JSONL files for each feed. Each line in a JSONL file is a serialized `TelemetryFrame` object, enabling sequential replay and analysis of captured sessions.
+Each recording has a `manifest.json` with metadata (game, track, car, use case, status, timestamps) and JSONL files for each feed. Each line is a serialized `TelemetryFrame` object.
+
+### Session-Based Analysis
+
+Use-case sessions allow targeted data capture and analysis:
+
+1. **Create a session** with a use case (`shift_points` or `track_map`)
+2. **Start runs** — each run captures frames from the ring buffer between start and stop
+3. **Complete the session** — auto-analyzes captured data and stores results
+4. **Retrieve analysis** — shift point RPM ranges or track boundary coordinates
+
+Sessions are in-memory and independent of persistent recordings.
 
 ## REST API
 
@@ -159,6 +171,15 @@ A built-in HTTP API server runs on port 8080 for recording management and live t
 | 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/sessions` | List all sessions |
+| POST | `/api/sessions` | Create analysis session |
+| GET | `/api/sessions/{id}` | Get session details |
+| DELETE | `/api/sessions/{id}` | Delete session |
+| POST | `/api/sessions/{id}/runs` | Start a run |
+| POST | `/api/sessions/{id}/runs/{run_id}/stop` | Stop a run |
+| POST | `/api/sessions/{id}/complete` | Complete session + auto-analyze |
+| GET | `/api/sessions/{id}/analysis` | Get analysis results |
+| POST | `/api/sessions/{id}/analyze` | Re-run analysis on completed session |
 
 ### Start Recording Body
 
@@ -200,6 +221,40 @@ All fields are optional.
 }
 ```
 
+### Create Session Body
+
+```json
+{
+  "use_case": "shift_points",
+  "label": "Shift Point Analysis Run 1"
+}
+```
+
+### Start Run Body
+
+```json
+{
+  "feed_name": "ksudp",
+  "label": "Acceleration runs"
+}
+```
+
+### Shift Point Analysis Response
+
+```json
+{
+  "gear_ranges": [
+    { "gear": 2, "gear_display": "1", "min_rpm": 3200, "max_rpm": 8500, "avg_rpm": 6100, "sample_count": 1200 },
+    { "gear": 3, "gear_display": "2", "min_rpm": 5800, "max_rpm": 8400, "avg_rpm": 7200, "sample_count": 900 }
+  ],
+  "shift_events": [
+    { "from_gear": 2, "to_gear": 3, "rpm_before_shift": 8400, "rpm_after_shift": 6100, "rpm_drop": 2300, "speed_kmh": 95.0 }
+  ],
+  "recommended_shift_rpm": 8400.0,
+  "total_frames_analyzed": 2100
+}
+```
+
 ## Testing
 
 ```bash
@@ -217,9 +272,11 @@ cargo test
 ```
 src/
 ├── main.rs                 Multi-port UDP listener, TUI event loop, KSUDP handshake
-├── api.rs                  REST API server (axum) for recording management and live telemetry
+├── api.rs                  REST API server (axum) — recordings, sessions, live telemetry
+├── recording.rs            Recording manager — ring buffers, manifest CRUD, flush to JSONL
+├── session.rs              Session manager — use-case sessions, runs, frame extraction
+├── analysis.rs             Analysis algorithms — shift points, track mapping
 ├── binary_utils.rs         Shared safe binary read helpers (bounds-checked, zero fallback)
-├── recording.rs            Recording session manager (manifest, CRUD, auto-start)
 ├── telemetry_frame.rs      Unified telemetry data model (TelemetryFrame)
 ├── feed_state.rs           Per-feed health/frequency state machine with ring buffer
 ├── parser_ksudp.rs         AC KSUDP binary parser (RTCarInfo, 6 tests)