docs: update trace API ref + API dictionary to V4.1

docs_v1.0/API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md

@@ -1,7 +1,7 @@
 # Trace API v1.0.0 Reference — M5 Official
 
 **Author**: M5  
-**Date**: 2026-05-07  
+**Date**: 2026-05-14  
 **Status**: ✅ Production — implemented and verified on Charade (Job 255)
 
 ---
@@ -179,30 +179,35 @@ height = prev.h + (next.h - prev.h) * t
 
 **`GET /api/v1/file/:file_uuid/trace/:trace_id/video`**
 
-MP4 video segment for a face trace. Two modes available:
-
-**Normal mode**: raw video segment, no overlays, stream copy (fastest).
-
-**Debug mode** (default): with bounding box + debug overlay.
+MP4 video segment for a face trace. Two modes:
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
 | `padding` | float | 2.0 | Padding seconds before/after |
-| `mode` | string | `debug` | `normal` = raw clip, `debug` = with overlay |
+| `mode` | string | `normal` | `normal` = raw clip (`-c copy`), `debug` = with overlay (re-encode) |
 
-**Debug mode overlay info (top-left):**
+**Normal mode** (default): raw video segment, no overlays, stream copy (fastest).
+
+**Debug mode**: re-encoded with text info panel + green bounding boxes.
+
+**Debug overlay (bottom-left):**
 ```
-Trace: <ID>  Cut: <scene>  <identity_name>
-Frame: <N>  UUID: <file_uuid>
+Frame {n}  {pts}s
+Cut: {id}
+{file_uuid}
+Trace {id}: start={frame}  {name}
+...
 ```
 
+Green bbox: actual detection frames `thickness=4`, interpolated `thickness=1`.
+
 **Usage:**
 ```bash
-# Debug mode (default, backward compatible)
-curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video"
-
-# Normal mode (no overlay, faster)
+# Normal mode (default)
 curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video?mode=normal"
+
+# Debug mode
+curl -o trace.mp4 "https://host/api/v1/file/{uuid}/trace/{id}/video?mode=debug"
 ```
 
 ---