diff --git a/docs/CLUSTER_AGENT_IMPLEMENTED.md b/docs/CLUSTER_AGENT_IMPLEMENTED.md
new file mode 100644
index 0000000..4e0cede
--- /dev/null
+++ b/docs/CLUSTER_AGENT_IMPLEMENTED.md
@@ -0,0 +1,50 @@
+# Cluster Agent Endpoint — 實作完成
+
+## 新增 Endpoint
+
+**`POST /api/v1/file/:file_uuid/cluster-agent`** — 對指定影片觸發 on-demand face clustering。
+
+## 實作邏輯
+
+1. 查 DB 拿 `file_path`、`fps`，從 `probe_json` 拿 `nb_frames`
+2. 執行 Python `fast_face_clustering_processor.py`（不接受 --frames）
+3. 將分組結果寫入 `tkg_nodes`（`label` = `cluster_id`）
+4. 回傳 Response
+
+## 前端消費流程（不變）
+
+```
+POST /api/v1/file/{uuid}/cluster-agent → 觸發 clustering
+GET  /api/v1/file/{uuid}/face-groups   → 輪詢結果
+```
+
+## Response (200)
+
+```json
+{
+  "success": true,
+  "file_uuid": "477b24d3...",
+  "message": "Clustering completed",
+  "clusters": 25,
+  "total_traces": 37
+}
+```
+
+## 狀態
+
+- ✅ Code 完成、已部署
+- ✅ 測試通過：`477b24d3...` → 25 clusters, 37 traces
+
+## 其他修復（同次部署）
+
+- OCR chunks 現在正確標為 `source_type: ocr`
+- Rule 1 重跑會先刪舊 chunks
+- `store_traced_faces.py` 失敗時寫入 fallback 避免 worker 卡住
+
+## 相關檔案
+
+- `src/api/cluster_agent.rs` — 新 endpoint handler
+- `src/api/server.rs` — route 註冊
+- `src/core/chunk/rule1_ingest.rs` — 先刪舊 chunks
+- `src/core/db/postgres_db.rs` — chunk_type 用 as_str()
+- `src/worker/job_worker.rs` — fallback face_traced.json