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

docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md

@@ -1,6 +1,6 @@
 # API Dictionary v1.0.0
 
-53 endpoints across 10 modules. Auth: `X-API-Key` header.
+58 endpoints across 10 modules. Auth: `X-API-Key` header or `Authorization: Bearer <key>`.
 
 ## API Design Principle
 
@@ -128,7 +128,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | 43 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (optional crop via `?frame=&x=&y=&w=&h=`) |
 | 44 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream (`?start=&end=` for range) |
 | 45 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay video (`?start=&end=&duration=`) |
-| 46 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip with bbox overlay (`?padding=`) |
+| 46 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (`?mode=normal\|debug&padding=`) |
 
 ## Identity Delete
 
@@ -150,6 +150,13 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | 55 | POST | `/api/v1/agents/suggest/merge` | Suggest identity merge |
 | 56 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering |
 
+## Identity Search (identity_api.rs, new in V4.1)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 57 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunk results |
+| 58 | GET | `/api/v1/search/identity_text?q=&uuid=` | Full-text search → identity-bound chunks |
+
 ---
 
 ## Summary
@@ -157,7 +164,7 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | Module | Routes | File |
 |--------|--------|------|
 | Core | 21 | `server.rs` |
-| File/Identity | 12 | `identity_api.rs` |
+| File/Identity | 14 | `identity_api.rs` (+2 search endpoints) |
 | Binding | 3 | `identity_binding.rs` |
 | Faces | 1 | `identities.rs` |
 | Search | 3 | `search.rs`, `universal_search.rs` |
@@ -165,4 +172,4 @@ Every path segment after the resource ID is a **verb** — an action on that res
 | Media | 4 | `media_api.rs` |
 | Identity Delete | 1 | `identity_api.rs` |
 | Agents | 9 | `agent_api.rs`, `five_w1h_agent_api.rs`, `identity_agent_api.rs` |
-| **Total** | **56** | |
+| **Total** | **58** | |

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"
 ```
 
 ---