diff --git a/docs/src/Icomm.SmartPool.Proxy/CLIENT_MIGRATION_NOTES.md b/docs/src/Icomm.SmartPool.Proxy/CLIENT_MIGRATION_NOTES.md
new file mode 100644
index 0000000..f8cd88f
--- /dev/null
+++ b/docs/src/Icomm.SmartPool.Proxy/CLIENT_MIGRATION_NOTES.md
@@ -0,0 +1,105 @@
+# SmartPool Client Migration Notes
+
+Tai lieu nay tong hop cac thay doi phia client de cac service dang su dung `Icomm.SmartPool.Proxy` cap nhat nhanh.
+
+## Scope
+
+Ap dung cho cac thay doi moi cua logging flow:
+- Logging luon chay doc lap (fire-and-forget)
+- Retry bang channel + batch flush
+- Tach timeout cho request chinh va request log
+
+## Breaking Changes
+
+### 1) SmartPoolOptions renamed/removed
+
+- Renamed:
+  - `TimeoutMs` -> `RequestTimeoutMs`
+  - `LogBatchSize` -> `LogRetryMaxBatchSize`
+  - `LogBatchFlushIntervalMs` -> `LogRetryFlushIntervalMs`
+- Removed:
+  - `EnableBatchLogging`
+  - `EnableFireAndForgetLogging`
+
+### 2) Logging mode options removed
+
+Khong con bat/tat "batch mode" hay "fire-and-forget mode" bang option:
+- Logging hien tai mac dinh la non-blocking.
+- Neu gui log that bai lan dau, log duoc dua vao retry channel.
+- Retry batch that bai tiep se bi bo (best-effort).
+
+## Timeout Behavior (new)
+
+- `RequestTimeoutMs`:
+  - Dung cho non-log requests (GetProxy/Ping)
+  - Dung cho HTTP client timeout va gRPC deadline cua non-log calls
+- `LogRequestTimeoutMs`:
+  - Dung rieng cho log send (single + retry batch)
+  - Log gRPC calls khong dung `RequestTimeoutMs` deadline nua de tranh timeout chong nhau
+
+## Config Migration
+
+### Before
+
+```json
+{
+  "SmartPool": {
+    "TimeoutMs": 30000,
+    "EnableFireAndForgetLogging": true,
+    "EnableBatchLogging": true,
+    "LogBatchSize": 50,
+    "LogBatchFlushIntervalMs": 5000
+  }
+}
+```
+
+### After
+
+```json
+{
+  "SmartPool": {
+    "RequestTimeoutMs": 30000,
+    "LogRequestTimeoutMs": 3000,
+    "LogRetryMaxBatchSize": 50,
+    "LogRetryFlushIntervalMs": 5000
+  }
+}
+```
+
+## DI Preset Migration
+
+Neu service dang set options trong code:
+
+### Before
+
+```csharp
+services.AddSmartPoolClient(options =>
+{
+    options.TimeoutMs = 30000;
+    options.EnableFireAndForgetLogging = true;
+    options.EnableBatchLogging = true;
+    options.LogBatchSize = 50;
+    options.LogBatchFlushIntervalMs = 5000;
+});
+```
+
+### After
+
+```csharp
+services.AddSmartPoolClient(options =>
+{
+    options.RequestTimeoutMs = 30000;
+    options.LogRequestTimeoutMs = 3000;
+    options.LogRetryMaxBatchSize = 50;
+    options.LogRetryFlushIntervalMs = 5000;
+});
+```
+
+## Notes for Service Owners
+
+- Khong can doi call-site `LogProxyUsageAsync(...)`:
+  - Method van tra `Task<bool>` de giu compatibility.
+  - Hanh vi hien tai la best-effort non-blocking.
+- Neu service can "guaranteed logging", can bo sung co che queue/persist o layer service.
+- Nen cap nhat tat ca `appsettings*.json` va env mapping de dung key moi.
+
diff --git a/docs/src/Icomm.SmartPool.Proxy/README.md b/docs/src/Icomm.SmartPool.Proxy/README.md
index 82d5e54..6f15ab2 100644
--- a/docs/src/Icomm.SmartPool.Proxy/README.md
+++ b/docs/src/Icomm.SmartPool.Proxy/README.md
@@ -3,6 +3,8 @@
 Client SDK for SmartPool proxy management system. Supports both gRPC and HTTP protocols.
 
 > 📖 **Xem tài liệu chi tiết**: [SDK_DOCUMENTATION.md](./SDK_DOCUMENTATION.md)
+>
+> 📌 **Migration note (quan trọng)**: [CLIENT_MIGRATION_NOTES.md](./CLIENT_MIGRATION_NOTES.md)
 
 ## ✨ Features
 
@@ -65,7 +67,10 @@ Add to `appsettings.json`:
     "Port": 5001,
     "UseSecureConnection": false,
     "DefaultAccessToken": "your-access-token",
-    "TimeoutMs": 30000
+    "RequestTimeoutMs": 30000,
+    "LogRequestTimeoutMs": 3000,
+    "LogRetryMaxBatchSize": 50,
+    "LogRetryFlushIntervalMs": 5000
   }
 }
 ```