docs: sync case-insensitive variant

docs: update API Ref (V4.2), CHANGELOG, Release Notes for de88fd4e
2026-05-25 10:31:37 +08:00 · 2026-05-25 10:31:32 +08:00
5 changed files with 303 additions and 142 deletions
--- a/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_V1.0.0.md
@@ -2,15 +2,15 @@
 document_type: "reference_doc"
 service: "MOMENTRY_CORE"
 title: "Momentry Core Release API Reference v1.0.0"
-date: "2026-05-14"
-version: "V4.1"
+date: "2026-05-25"
+version: "V4.2"
 status: "active"
 owner: "Warren"
 ---

 # Momentry Core API Reference v1.0.0

-58 endpoints across 10 categories, with real curl examples and responses.
+55 endpoints across 10 categories, with real curl examples and responses.

 ## Base

@@ -30,12 +30,13 @@ owner: "Warren"
 |---|--------|------|-------------|
 | 1 | GET | `/health` | Server status (ok/degraded) |
 | 2 | GET | `/health/detailed` | Per-service health + latency |
-| 3 | POST | `/api/v1/auth/login` | Username/password → API key |
-| 4 | POST | `/api/v1/auth/logout` | Invalidate session |
-| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
+| 3 | GET | `/health/consistency` | Data consistency check |
+| 4 | POST | `/api/v1/auth/login` | Username/password → API key |
+| 5 | POST | `/api/v1/auth/logout` | Invalidate session |
 | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status |
-| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health |
-| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache |
+| 7 | POST | `/api/v1/config/cache` | Toggle Redis cache |
+| 8 | POST | `/api/v1/config/auto-pipeline` | Toggle auto-pipeline on register |
+| 9 | POST | `/api/v1/config/watcher-auto-register` | Toggle watcher auto-register |

 ```bash
 curl http://localhost:3002/health
@@ -44,8 +45,8 @@ curl http://localhost:3002/health
 {
  "status": "ok",
  "version": "1.0.0",
-  "build_git_hash": "26f2434",
-  "build_timestamp": "2026-05-14T09:09:17Z",
+  "build_git_hash": "de88fd4e",
+  "build_timestamp": "2026-05-25",
  "uptime_ms": 7052517
 }
 ```
@@ -68,8 +69,8 @@ Supports all file types (video, image, document, audio). SHA256 content_hash com
 ```json
 {
  "status": "ok",
-  "build_git_hash": "26f2434",
-  "build_timestamp": "2026-05-14T09:09:17Z",
+  "build_git_hash": "de88fd4e",
+  "build_timestamp": "2026-05-25",
  "services": {
    "postgres": {"status": "ok", "latency_ms": 6},
    "redis":    {"status": "ok", "latency_ms": 0},
@@ -103,17 +104,17 @@ Supports all file types (video, image, document, audio). SHA256 content_hash com

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 9 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` |
-| 10 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename |
-| 11 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) |
-| 12 | GET | `/api/v1/files/scan` | Scan directory for new files |
-| 13 | GET | `/api/v1/files` | List files (paginated) |
-| 14 | GET | `/api/v1/file/:file_uuid` | Single file detail |
-| 15 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
-| 16 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
-| 17 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
-| 18 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
-| 19 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |
+| 10 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` |
+| 11 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename |
+| 12 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) |
+| 13 | GET | `/api/v1/files/scan` | Scan directory for new files |
+| 14 | GET | `/api/v1/files` | List files (paginated) |
+| 15 | GET | `/api/v1/file/:file_uuid` | Single file detail |
+| 16 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
+| 17 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
+| 18 | POST | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
+| 19 | POST | `/api/v1/progress/:file_uuid` | Processing progress |
+| 20 | POST | `/api/v1/jobs` | Monitor jobs (filterable) |

 ```bash
 curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_path":"/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"}'
@@ -154,14 +155,14 @@ curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muse

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 20 | POST | `/api/v1/search/visual` | Visual chunk search |
-| 21 | POST | `/api/v1/search/visual/class` | By object class |
-| 22 | POST | `/api/v1/search/visual/density` | By spatial density |
-| 23 | POST | `/api/v1/search/visual/combination` | Combined visual search |
-| 24 | POST | `/api/v1/search/visual/stats` | Visual stats |
-| 25 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) |
-| 26 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
-| 27 | POST | `/api/v1/search/frames` | Frame-level search |
+| 21 | POST | `/api/v1/search/visual` | Visual chunk search |
+| 22 | POST | `/api/v1/search/visual/class` | By object class |
+| 23 | POST | `/api/v1/search/visual/density` | By spatial density |
+| 24 | POST | `/api/v1/search/visual/combination` | Combined visual search |
+| 25 | POST | `/api/v1/search/visual/stats` | Visual stats |
+| 26 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) |
+| 27 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
+| 28 | POST | `/api/v1/search/frames` | Frame-level search |

 ```bash
 curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"query":"name","limit":2,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
@@ -183,10 +184,10 @@ curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 28 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) |
-| 29 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) |
+| 29 | POST | `/api/v1/file/:file_uuid/traces` | List traces (sorted/filtered) |
+| 30 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) |

-### sortby — list traces
+### traces — list traces

 Parameters:
 - `sort_by`: `face_count` | `duration` | `first_appearance`
@@ -194,7 +195,7 @@ Parameters:
 - `limit`: max results

 ```bash
-curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/face_trace/sortby"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"sort_by":"face_count","limit":2}'
+curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/traces"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"sort_by":"face_count","limit":2}'
 ```
 ```json
 {"success":true,"total_traces":6892,"total_faces":108204,"traces":[
@@ -224,10 +225,10 @@ curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 30 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) |
-| 31 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). |
-| 32 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. |
-| 33 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) |
+| 31 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) |
+| 32 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). |
+| 33 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. |
+| 34 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) |

 All video endpoints support:
 - `mode=normal|debug` (default: `normal`)
@@ -260,16 +261,16 @@ Green bbox per face detection: actual frames `thickness=4`, interpolated `thickn

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 33 | GET | `/api/v1/identities` | List all identities |
-| 34 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file |
-| 35 | POST | `/api/v1/identity` | Register new identity |
-| 36 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
-| 37 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
-| 38 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
-| 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
-| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
-| 41 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
-| 42 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |
+| 35 | GET | `/api/v1/identities` | List all identities |
+| 36 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file |
+| 37 | POST | `/api/v1/identity` | Register new identity |
+| 38 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
+| 39 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
+| 40 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
+| 41 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
+| 42 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
+| 43 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
+| 44 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |

 ```bash
 curl "http://localhost:3002/api/v1/identities?page=1&page_size=3"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -307,9 +308,9 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2"  -H "X-A

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 43 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
-| 44 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
-| 45 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |
+| 45 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
+| 46 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
+| 47 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |

 ```bash
 curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'
@@ -324,9 +325,9 @@ curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 46 | POST | `/api/v1/resource/register` | Register processing resource |
-| 47 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
-| 48 | GET | `/api/v1/resources` | List all resources |
+| 48 | POST | `/api/v1/resource/register` | Register processing resource |
+| 49 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
+| 50 | GET | `/api/v1/resources` | List all resources |

 ```bash
 curl "http://localhost:3002/api/v1/resources"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -341,10 +342,10 @@ curl "http://localhost:3002/api/v1/resources"  -H "X-API-Key: muser_686008560363

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 49 | POST | `/api/v1/agents/translate` | AI text translation |
-| 50 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis |
-| 51 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
-| 52 | GET | `/api/v1/agents/5w1h/status` | Job status |
+| 51 | POST | `/api/v1/agents/translate` | AI text translation |
+| 52 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis |
+| 53 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
+| 54 | GET | `/api/v1/agents/5w1h/status` | Job status |

 ```bash
 curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"text":"Hello world","target_language":"zh-TW"}'
@@ -359,11 +360,10 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: mus

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 53 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file |
-| 54 | GET | `/api/v1/agents/identity/status` | Analysis status |
-| 55 | POST | `/api/v1/agents/identity/suggest` | Name suggestions |
-| 56 | POST | `/api/v1/agents/suggest/merge` | Suggest merge |
-| 57 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering |
+| 55 | POST | `/api/v1/agents/identity/match-from-photo` | Match face from photo |
+| 56 | POST | `/api/v1/agents/identity/match-from-trace` | Match face from trace |
+| 57 | POST | `/api/v1/agents/suggest/merge` | Suggest merge |
+| 58 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering |

 ---

@@ -371,10 +371,11 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: mus

 | Version | Date | Changes |
 |---------|------|---------|
+| V4.2 | 2026-05-25 | Removed phantom routes (stats/ingest, stats/inference, agents/identity/status); fixed HTTP methods (chunk, progress, jobs → POST); renamed endpoints (face_trace/sortby → traces, analyze → match-from-photo, suggest → match-from-trace); added config endpoints (consistency, auto-pipeline, watcher-auto-register); updated git hash to de88fd4e |
 | V4.1 | 2026-05-14 | Added `build_timestamp` + `resources` + `pipeline` to health APIs; identity search endpoints; trace debug rework (green bbox, text overlay, all traces listed) |

 ## Related

- `API_DICTIONARY_V1.0.0.md` — Quick reference (58 endpoints)
+- `API_DICTIONARY_V1.0.0.md` — Quick reference (55 endpoints)
 - `API_DOCUMENTATION_v1.0.0.md` — Detailed spec with examples
 - `TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific reference
--- a/docs_v1.0/API_V1.0.0/API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/API_REFERENCE_v1.0.0.md
@@ -2,21 +2,21 @@
 document_type: "reference_doc"
 service: "MOMENTRY_CORE"
 title: "Momentry Core Release API Reference v1.0.0"
-date: "2026-05-14"
-version: "V4.1"
+date: "2026-05-25"
+version: "V4.2"
 status: "active"
 owner: "Warren"
 ---

 # Momentry Core API Reference v1.0.0

-58 endpoints across 10 categories, with real curl examples and responses.
+55 endpoints across 10 categories, with real curl examples and responses.

 ## Base

 | Environment | URL |
 |-------------|-----|
-| Production | `http://localhost:3002` or `https://m5api.momentry.ddns.net` |
+| Production | `http://localhost:3002` or `https://api.momentry.ddns.net` |
 | Development | `http://localhost:3003` |
 | Auth | Header `X-API-Key: <key>` (login endpoint unprotected) |

@@ -30,14 +30,13 @@ owner: "Warren"
 |---|--------|------|-------------|
 | 1 | GET | `/health` | Server status (ok/degraded) |
 | 2 | GET | `/health/detailed` | Per-service health + latency |
-| 3 | POST | `/api/v1/auth/login` | Username/password → API key |
-| 4 | POST | `/api/v1/auth/logout` | Invalidate session |
-| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
+| 3 | GET | `/health/consistency` | Data consistency check |
+| 4 | POST | `/api/v1/auth/login` | Username/password → API key |
+| 5 | POST | `/api/v1/auth/logout` | Invalidate session |
 | 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo status |
-| 7 | GET | `/api/v1/stats/inference` | LLM/Embedding health |
-| 8 | POST | `/api/v1/config/cache` | Toggle Redis cache |
-| 9 | POST | `/api/v1/config/auto-pipeline` | Toggle auto-pipeline on register |
-| 10 | POST | `/api/v1/config/watcher-auto-register` | Toggle watcher auto-register |
+| 7 | POST | `/api/v1/config/cache` | Toggle Redis cache |
+| 8 | POST | `/api/v1/config/auto-pipeline` | Toggle auto-pipeline on register |
+| 9 | POST | `/api/v1/config/watcher-auto-register` | Toggle watcher auto-register |

 ```bash
 curl http://localhost:3002/health
@@ -46,8 +45,8 @@ curl http://localhost:3002/health
 {
  "status": "ok",
  "version": "1.0.0",
-  "build_git_hash": "26f2434",
-  "build_timestamp": "2026-05-14T09:09:17Z",
+  "build_git_hash": "de88fd4e",
+  "build_timestamp": "2026-05-25",
  "uptime_ms": 7052517
 }
 ```
@@ -70,8 +69,8 @@ Supports all file types (video, image, document, audio). SHA256 content_hash com
 ```json
 {
  "status": "ok",
-  "build_git_hash": "26f2434",
-  "build_timestamp": "2026-05-14T09:09:17Z",
+  "build_git_hash": "de88fd4e",
+  "build_timestamp": "2026-05-25",
  "services": {
    "postgres": {"status": "ok", "latency_ms": 6},
    "redis":    {"status": "ok", "latency_ms": 0},
@@ -105,17 +104,17 @@ Supports all file types (video, image, document, audio). SHA256 content_hash com

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 9 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` |
-| 10 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename |
-| 11 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) |
-| 12 | GET | `/api/v1/files/scan` | Scan directory for new files |
-| 13 | GET | `/api/v1/files` | List files (paginated) |
-| 14 | GET | `/api/v1/file/:file_uuid` | Single file detail |
-| 15 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
-| 16 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
-| 17 | GET | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
-| 18 | GET | `/api/v1/progress/:file_uuid` | Processing progress |
-| 19 | GET | `/api/v1/jobs` | Monitor jobs (filterable) |
+| 10 | POST | `/api/v1/files/register` | Register file → file_uuid. Body: `{"file_path":"...", "content_hash":"optional"}` |
+| 11 | GET | `/api/v1/files/lookup?file_name=` | Pre-upload name conflict check. Returns matches + `next_name` for auto-rename |
+| 12 | POST | `/api/v1/unregister` | Unregister file(s): by `file_uuid` or pattern match (`file_path`+`pattern`) |
+| 13 | GET | `/api/v1/files/scan` | Scan directory for new files |
+| 14 | GET | `/api/v1/files` | List files (paginated) |
+| 15 | GET | `/api/v1/file/:file_uuid` | Single file detail |
+| 16 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
+| 17 | POST | `/api/v1/file/:file_uuid/process` | Start pipeline |
+| 18 | POST | `/api/v1/file/:file_uuid/chunk/:chunk_id` | Single chunk detail (V1.0.2+) |
+| 19 | POST | `/api/v1/progress/:file_uuid` | Processing progress |
+| 20 | POST | `/api/v1/jobs` | Monitor jobs (filterable) |

 ```bash
 curl -X POST http://localhost:3002/api/v1/files/register  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_path":"/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"}'
@@ -156,14 +155,14 @@ curl "http://localhost:3002/api/v1/files?page=1&page_size=2" -H "X-API-Key: muse

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 20 | POST | `/api/v1/search/visual` | Visual chunk search |
-| 21 | POST | `/api/v1/search/visual/class` | By object class |
-| 22 | POST | `/api/v1/search/visual/density` | By spatial density |
-| 23 | POST | `/api/v1/search/visual/combination` | Combined visual search |
-| 24 | POST | `/api/v1/search/visual/stats` | Visual stats |
-| 25 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) |
-| 26 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
-| 27 | POST | `/api/v1/search/frames` | Frame-level search |
+| 21 | POST | `/api/v1/search/visual` | Visual chunk search |
+| 22 | POST | `/api/v1/search/visual/class` | By object class |
+| 23 | POST | `/api/v1/search/visual/density` | By spatial density |
+| 24 | POST | `/api/v1/search/visual/combination` | Combined visual search |
+| 25 | POST | `/api/v1/search/visual/stats` | Visual stats |
+| 26 | POST | `/api/v1/search/smart` | Semantic (EmbeddingGemma + pgvector) |
+| 27 | POST | `/api/v1/search/universal` | BM25 keyword (requires file_uuid) |
+| 28 | POST | `/api/v1/search/frames` | Frame-level search |

 ```bash
 curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"query":"name","limit":2,"mode":"bm25","file_uuid":"3abeee81d94597629ed8cb943f182e94"}'
@@ -185,10 +184,10 @@ curl -X POST http://localhost:3002/api/v1/search/universal  -H "X-API-Key: muser

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 28 | POST | `/api/v1/file/:file_uuid/face_trace/sortby` | List traces (sorted/filtered) |
-| 29 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) |
+| 29 | POST | `/api/v1/file/:file_uuid/traces` | List traces (sorted/filtered) |
+| 30 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/faces` | Trace detections (+ interpolation) |

-### sortby — list traces
+### traces — list traces

 Parameters:
 - `sort_by`: `face_count` | `duration` | `first_appearance`
@@ -196,7 +195,7 @@ Parameters:
 - `limit`: max results

 ```bash
-curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/face_trace/sortby"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"sort_by":"face_count","limit":2}'
+curl -X POST "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/traces"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"sort_by":"face_count","limit":2}'
 ```
 ```json
 {"success":true,"total_traces":6892,"total_faces":108204,"traces":[
@@ -226,10 +225,10 @@ curl "http://localhost:3002/api/v1/file/3abeee81d94597629ed8cb943f182e94/trace/2

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 30 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) |
-| 31 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). |
-| 32 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. |
-| 33 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) |
+| 31 | GET | `/api/v1/file/:file_uuid/thumbnail` | Frame JPEG (?frame=&x=&y=&w=&h=) |
+| 32 | GET | `/api/v1/file/:file_uuid/video` | Raw video stream. Dual input: `?start_time=&end_time=` (seconds) or `?start_frame=&end_frame=` (frames). |
+| 33 | GET | `/api/v1/file/:file_uuid/video/bbox` | Bbox overlay. `?start_frame=&end_frame=&face_uuid=&duration=` (all frame numbers). Dual input via `start_time`/`end_time`. |
+| 34 | GET | `/api/v1/file/:file_uuid/trace/:trace_id/video` | Trace clip (?mode=&padding=&audio=) |

 All video endpoints support:
 - `mode=normal|debug` (default: `normal`)
@@ -262,16 +261,16 @@ Green bbox per face detection: actual frames `thickness=4`, interpolated `thickn

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 33 | GET | `/api/v1/identities` | List all identities |
-| 34 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file |
-| 35 | POST | `/api/v1/identity` | Register new identity |
-| 36 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
-| 37 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
-| 38 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
-| 39 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
-| 40 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
-| 41 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
-| 42 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |
+| 35 | GET | `/api/v1/identities` | List all identities |
+| 36 | GET | `/api/v1/file/:file_uuid/identities` | Identities in a file |
+| 37 | POST | `/api/v1/identity` | Register new identity |
+| 38 | GET | `/api/v1/identity/:identity_uuid` | Identity detail |
+| 39 | DELETE | `/api/v1/identity/:identity_uuid` | Delete identity |
+| 40 | GET | `/api/v1/identity/:identity_uuid/files` | Files for identity |
+| 41 | GET | `/api/v1/identity/:identity_uuid/chunks` | Chunks for identity |
+| 42 | GET | `/api/v1/faces/candidates` | Unbound face gallery |
+| 43 | GET | `/api/v1/identities/search?q=` | Search identities by name → chunks |
+| 44 | GET | `/api/v1/search/identity_text?q=&file_uuid=` | Full-text search → identity-bound chunks |

 ```bash
 curl "http://localhost:3002/api/v1/identities?page=1&page_size=3"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -309,9 +308,9 @@ curl "http://localhost:3002/api/v1/faces/candidates?page=1&page_size=2"  -H "X-A

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 43 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
-| 44 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
-| 45 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |
+| 45 | POST | `/api/v1/identity/:identity_uuid/bind` | Bind face → identity |
+| 46 | POST | `/api/v1/identity/:identity_uuid/unbind` | Unbind face from identity |
+| 47 | POST | `/api/v1/identity/:identity_uuid/mergeinto` | Merge into another identity |

 ```bash
 curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c1a57dff4/bind"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"file_uuid":"3abeee81d94597629ed8cb943f182e94","face_id":"face_42"}'
@@ -326,9 +325,9 @@ curl -X POST "http://localhost:3002/api/v1/identity/a9a90105-6d6b-46ff-92da-0c3c

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 46 | POST | `/api/v1/resource/register` | Register processing resource |
-| 47 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
-| 48 | GET | `/api/v1/resources` | List all resources |
+| 48 | POST | `/api/v1/resource/register` | Register processing resource |
+| 49 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
+| 50 | GET | `/api/v1/resources` | List all resources |

 ```bash
 curl "http://localhost:3002/api/v1/resources"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
@@ -343,10 +342,10 @@ curl "http://localhost:3002/api/v1/resources"  -H "X-API-Key: muser_686008560363

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 49 | POST | `/api/v1/agents/translate` | AI text translation |
-| 50 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis |
-| 51 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
-| 52 | GET | `/api/v1/agents/5w1h/status` | Job status |
+| 51 | POST | `/api/v1/agents/translate` | AI text translation |
+| 52 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk analysis |
+| 53 | POST | `/api/v1/agents/5w1h/batch` | Batch analysis |
+| 54 | GET | `/api/v1/agents/5w1h/status` | Job status |

 ```bash
 curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"  -H "Content-Type: application/json"  -d '{"text":"Hello world","target_language":"zh-TW"}'
@@ -361,11 +360,10 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: mus

 | # | Method | Path | Description |
 |---|--------|------|-------------|
-| 53 | POST | `/api/v1/agents/identity/analyze` | Identify faces in file |
-| 54 | GET | `/api/v1/agents/identity/status` | Analysis status |
-| 55 | POST | `/api/v1/agents/identity/suggest` | Name suggestions |
-| 56 | POST | `/api/v1/agents/suggest/merge` | Suggest merge |
-| 57 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering |
+| 55 | POST | `/api/v1/agents/identity/match-from-photo` | Match face from photo |
+| 56 | POST | `/api/v1/agents/identity/match-from-trace` | Match face from trace |
+| 57 | POST | `/api/v1/agents/suggest/merge` | Suggest merge |
+| 58 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering |

 ---

@@ -373,10 +371,11 @@ curl -X POST "http://localhost:3002/api/v1/agents/translate"  -H "X-API-Key: mus

 | Version | Date | Changes |
 |---------|------|---------|
+| V4.2 | 2026-05-25 | Removed phantom routes (stats/ingest, stats/inference, agents/identity/status); fixed HTTP methods (chunk, progress, jobs → POST); renamed endpoints (face_trace/sortby → traces, analyze → match-from-photo, suggest → match-from-trace); added config endpoints (consistency, auto-pipeline, watcher-auto-register); updated git hash to de88fd4e |
 | V4.1 | 2026-05-14 | Added `build_timestamp` + `resources` + `pipeline` to health APIs; identity search endpoints; trace debug rework (green bbox, text overlay, all traces listed) |

 ## Related

- `API_DICTIONARY_V1.0.0.md` — Quick reference (58 endpoints)
+- `API_DICTIONARY_V1.0.0.md` — Quick reference (55 endpoints)
 - `API_DOCUMENTATION_v1.0.0.md` — Detailed spec with examples
 - `TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific reference
--- a/docs_v1.0/API_V1.0.0/INTERNAL/DEV_API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/INTERNAL/DEV_API_REFERENCE_v1.0.0.md
@@ -158,6 +158,8 @@ related_documents:
 | 51 | GET | `/api/v1/stats/sftpgo` | SFTPGo 使用者狀態 | ✅ |
 | 52 | GET | `/api/v1/stats/inference` | 推理叢集健康狀態 | ✅ |
 | 53 | POST | `/api/v1/config/cache` | 切換快取開關 | ✅ |
+| 54 | POST | `/api/v1/config/auto-pipeline` | 註冊後自動處理 | ✅ |
+| 55 | POST | `/api/v1/config/watcher-auto-register` | Watcher 自動註冊 | ✅ |

 ---

--- a/docs_v1.0/REFERENCE/RELEASE_NOTES_v1.0.0.md
+++ b/docs_v1.0/REFERENCE/RELEASE_NOTES_v1.0.0.md
@@ -1,7 +1,7 @@
-# Release Notes — v1.0.0 (Production 3002)
+# Release Notes — v1.0.1 (Production 3002)

-**Date**: 2026-05-13
-**Build**: `301da08`
+**Date**: 2026-05-25
+**Build**: `de88fd4e`
 **Deployed by**: M4

 ---
@@ -101,6 +101,36 @@

 ---

+## Changes Since v1.0.0 (301da08 → de88fd4e)
+
+### Added
+- POST `/api/v1/agents/search` — Gemma4 function calling agent
+- POST `/api/v1/identity/:uuid/bind/trace` — trace-level identity binding
+- GET `/api/v1/file/:uuid/identities/:a/co-occur-with/:b` — co-occurrence
+- GET `/api/v1/file/:uuid/trace/:tid/thumbnail` — trace thumbnail
+- GET `/api/v1/file/:uuid/trace/:tid/representative-face` — representative face
+- PATCH `/api/v1/identity/:identity_uuid` — identity update + alias system
+- TKG extension: pose data + mutual gaze detection
+- `/health/consistency` — data consistency check
+- Config endpoints: cache toggle, auto-pipeline, watcher-auto-register
+- Representative frame auto-detection
+
+### Fixed
+- System consistency: store_vector, search, worker trigger reliability
+- trigger_processing: remove fake QUEUED state, create monitor_job if missing
+- stranger_id set to NULL on bind/merge operations
+- frame_number type: i32→i64 to match BIGINT schema
+- Compilation errors: restored PipelineType enum, pipeline() method, constants
+
+### Changed
+- Unified LLM config: CHAT_URL/VISION_URL/SUMMARY_URL with env var overrides
+- Port config centralized (8082 conflict resolved)
+- Resources API returns data (config+metadata)
+- server.rs split into modular route files
+- API Reference: 55 endpoints, removed phantom routes, fixed methods, renamed endpoints
+
+---
+
 ## Known Notes

 | Item | Note |
--- a/docs_v1.0/REFERENCE/history/CHANGELOG.md
+++ b/docs_v1.0/REFERENCE/history/CHANGELOG.md
@@ -6,13 +6,135 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

 ## [Unreleased]

+### Fixed
+- Compilation errors: restore PipelineType enum, pipeline() method, OLLAMA_URL/EMBED_URL/LLM_HEALTH_URL constants
+- frame_number type: changed i32→i64 to match BIGINT schema
+
+## [1.0.1] - 2026-05-25
+
+### Fixed
+- System consistency: store_vector, search, worker trigger reliability
+- trigger_processing: remove fake QUEUED state, create monitor_job if missing
+- stranger_id set to NULL on bind/merge operations
+- resource path cleanup
+
 ### Added
- Gitea API token integration
- n8n API key integration
- API key caching with Moka
- Rate limiting for API key validation
- Constant-time hash comparison
- OpenAPI documentation with utoipa
+- Frame/time pipeline split with output validation
+- `/api/v1/agents/search` — Gemma4 function calling agent
+- `/api/v1/identity/:uuid/bind/trace` — trace-level identity binding
+- `/api/v1/file/:uuid/identities/:a/co-occur-with/:b` — co-occurrence endpoint
+- `/api/v1/file/:uuid/trace/:tid/thumbnail` — trace thumbnail
+- `/api/v1/file/:uuid/trace/:tid/representative-face` — representative face
+- identity PATCH update, alias system, name UNIQUE removal
+- TKG extension: pose data + mutual gaze detection
+
+### Changed
+- Unified LLM config: CHAT_URL/VISION_URL/SUMMARY_URL with env var overrides
+- Refactored server.rs into modular route files
+- Port config centralized (8082 conflict resolved)
+- Resources API returns data (config+metadata); register source code resource
+
+## [1.0.0] - 2026-05-14
+
+### Added
+- Release version v1.0.0 tag
+- Production binary at port 3002
+- Playground binary at port 3003
+- Dedicated Gitea sync pipeline
+
+### Changed
+- Full V4.0 API reference published (55 endpoints)
+- Health APIs include build_timestamp + resources + pipeline
+- Qdrant refactored to use i64 for frame_number
+- Rust edition 2021, max_width=100, tab_spaces=4
+
+## [0.6.0] - 2026-05-01
+
+### Added
+- `/api/v1/agents/translate` — AI text translation
+- `/api/v1/agents/5w1h/batch` — batch analysis
+- `/api/v1/agents/identity/match-from-photo` — face matching from photo
+- `/api/v1/agents/identity/match-from-trace` — face matching from trace
+- `/api/v1/agents/suggest/merge` — merge suggestions
+- `/api/v1/agents/suggest/clustering` — re-clustering suggestions
+- `/api/v1/search/visual` endpoints (class, density, combination, stats)
+- `/api/v1/search/frames` — frame-level search
+- `/api/v1/faces/candidates` — unbound face gallery
+- `/api/v1/identities/search` — identity name search
+- `/api/v1/search/identity_text` — full-text identity-bound chunk search
+- `/health/consistency` — data consistency check
+- Config endpoints: auto-pipeline toggle, watcher-auto-register toggle
+- Cache toggle via `/api/v1/config/cache`
+
+### Fixed
+- Various type mismatches in DB layer (i64/i32 alignment)
+- Trace debug mode bbox rendering
+- Interpolation for sparse face detections
+
+## [0.5.0] - 2026-04-15
+
+### Added
+- `/api/v1/file/:file_uuid/traces` — trace listing (replaces face_trace/sortby)
+- `/api/v1/file/:file_uuid/trace/:trace_id/faces` — trace detections with interpolation
+- `/api/v1/file/:file_uuid/video/bbox` — bbox overlay video
+- `/api/v1/file/:file_uuid/trace/:trace_id/video` — trace clip (normal/debug mode)
+- File probe endpoint (`/api/v1/file/:file_uuid/probe`)
+- Jobs monitoring (`/api/v1/jobs`)
+- Processing progress (`/api/v1/progress/:file_uuid`)
+- Chunk detail (`/api/v1/file/:file_uuid/chunk/:chunk_id`)
+- `/api/v1/unregister` — file unregistration by uuid or pattern
+
+### Changed
+- face_trace/sortby renamed to `/api/v1/file/:file_uuid/traces`
+- Chunk/progress/jobs endpoints changed from GET to POST
+- Qdrant MongoDB dependency replaced with Rust-native driver
+- Redis upgraded to 1.0.x for performance
+
+## [0.4.0] - 2026-04-01
+
+### Added
+- Identity management: register, detail, delete, files, chunks
+- Identity binding: bind/unbind face → identity
+- Identity merging: mergeinto endpoint
+- Resource management: register, heartbeat, list
+- Docker health check integration
+- SFTPGo status endpoint
+- Pagination support for list endpoints
+
+### Changed
+- Database schema: `person_identities` table removed
+- N:N relationship via `file_identities` table
+- Architecture shift: Face → Identity (two-layer direct binding)
+- Terminology: `video_uuid` → `file_uuid` across all APIs
+
+## [0.3.0] - 2026-03-25
+
+### Added
+- `/api/v1/search/universal` — BM25 keyword search
+- `/api/v1/search/smart` — semantic search (pgvector)
+- `/api/v1/files/register` — file registration
+- `/api/v1/files/lookup` — name conflict check
+- `/api/v1/files/scan` — directory scan
+- File listing and detail endpoints
+- POST `/api/v1/file/:file_uuid/process` — processing pipeline trigger
+- `/api/v1/auth/login` and `/api/v1/auth/logout`
+- `/health/detailed` — per-service health check
+
+### Changed
+- Video processing pipeline refactored (ASR, OCR, YOLO, Face, Pose)
+- Centralized Python executor with timeout support
+- Logging unified under `logs/` directory
+- Startup scripts auto-build and kill old processes
+
+## [0.2.0] - 2026-03-22
+
+### Added
+- `/health` endpoint with status/build info
+- Video stream endpoint (`/api/v1/file/:file_uuid/video`)
+- Thumbnail extraction endpoint
+- FaceNet CoreML model integration
+- Basic API key authentication
+- PostgreSQL, MongoDB, Redis, Qdrant service initialization

 ## [0.1.0] - 2026-03-21

@@ -140,4 +262,11 @@ N8N_URL=https://n8n.momentry.ddns.net

 | Version | Date | Description |
 |---------|------|-------------|
+| 1.0.1 | 2026-05-25 | Bug fixes, agent endpoints, identity alias system, TKG extension |
+| 1.0.0 | 2026-05-14 | Release v1.0.0, V4.0 API reference, production binary |
+| 0.6.0 | 2026-05-01 | Agent endpoints (translate, 5w1h, identity match), search visual endpoints |
+| 0.5.0 | 2026-04-15 | Traces API, media endpoints, jobs/progress/chunk, rename face_trace→traces |
+| 0.4.0 | 2026-04-01 | Identity management, resource API, video_uuid→file_uuid rename |
+| 0.3.0 | 2026-03-25 | Search (BM25/semantic), file registration, health check, auth |
+| 0.2.0 | 2026-03-22 | Health endpoint, video stream, thumbnail, FaceNet model, DB init |
 | 0.1.0 | 2026-03-21 | Initial release with API Key Management |
Author	SHA1	Message	Date
Accusys	20dae387ee	docs: sync case-insensitive variant	2026-05-25 10:31:37 +08:00
Accusys	b9e93c6293	docs: update API Ref (V4.2), CHANGELOG, Release Notes for `de88fd4e`	2026-05-25 10:31:32 +08:00