diff --git a/__main__.py b/__main__.py
index 4c2c993..0f70253 100644
--- a/__main__.py
+++ b/__main__.py
@@ -17,6 +17,13 @@ def main() -> int:
     # a plain script (`python __main__.py`), `__package__` is empty so the
     # relative import fails — in that case put the package root (the parent
     # of this file's directory) on sys.path and use an absolute import.
+    """Điểm vào ``python -m cowork_local``.
+
+    Import muộn để công cụ kiểu ``-h`` và test nạp được gói mà không phải dựng cả
+    ứng dụng Qt. Chạy như script thường (``python __main__.py``) thì
+    ``__package__`` rỗng nên import tương đối hỏng — lúc đó đưa thư mục cha vào
+    ``sys.path`` và dùng import tuyệt đối.
+    """
     if __package__:
         from .app import run
     else:
diff --git a/app.py b/app.py
index 2249ee5..1db3034 100644
--- a/app.py
+++ b/app.py
@@ -61,6 +61,12 @@ def _set_windows_app_id() -> None:
 
 
 def run(argv: List[str] | None = None) -> int:
+    """Điểm vào ứng dụng: dựng Composition Root, gieo dữ liệu mặc định, áp theme
+    rồi mở cửa sổ chính.
+
+    Mọi bước gieo (skill dựng sẵn, flow dựng sẵn) đều bọc trong ``try`` — việc
+    dọn nhà không bao giờ được phép chặn app khởi động.
+    """
     argv = argv if argv is not None else sys.argv
     _set_windows_app_id()
     app = QApplication.instance() or QApplication(argv)
@@ -115,6 +121,7 @@ def run(argv: List[str] | None = None) -> int:
     win = MainWindow(ctx, user_name="local")
 
     def _reapply_system_theme(*_a):
+        """Theme đang để "Theo hệ thống" thì áp lại mỗi khi Windows đổi sáng/tối."""
         if ctx.config.theme == "system":
             set_active_theme("system")
             app.setStyleSheet(stylesheet("system"))
diff --git a/application/conversations/conversation_application_service.py b/application/conversations/conversation_application_service.py
index fdc9046..400e441 100644
--- a/application/conversations/conversation_application_service.py
+++ b/application/conversations/conversation_application_service.py
@@ -75,6 +75,12 @@ class ConversationApplicationService:
         permission_request: Optional[PermissionRequest] = None,
         attachment_reader: Optional[AttachmentReader] = None,
     ) -> None:
+        """Nhận vào các cổng (port) thay vì tự dựng phụ thuộc.
+
+        ``model`` và ``tools`` bắt buộc; mọi thứ còn lại là tuỳ chọn và để None thì
+        bỏ qua bước đó. Nhờ vậy test dựng được service với đúng phần nó cần kiểm,
+        không phải dựng cả provider thật lẫn sandbox.
+        """
         self._model = model
         self._tools = tools
         # Every hook is optional so the service degrades to a plain chat turn.
diff --git a/application/conversations/core_runtime_adapter.py b/application/conversations/core_runtime_adapter.py
index aabf714..0fea5ea 100644
--- a/application/conversations/core_runtime_adapter.py
+++ b/application/conversations/core_runtime_adapter.py
@@ -51,9 +51,11 @@ class CoreModelCall:
     """
 
     def __init__(self, provider: Any) -> None:
+        """Bọc một provider của ``core/`` vào cổng ``ModelCallPort``."""
         self._provider = provider
 
     def call(self, messages, tools, on_text=None, on_reasoning=None, cancel=None):
+        """Gọi model một lượt, có tự phục hồi khi tràn context hoặc bị giới hạn tốc độ."""
         from ...core.code_agent import _call_provider_with_recovery
 
         return _call_provider_with_recovery(self._provider, messages, tools, on_text,
@@ -66,6 +68,11 @@ class CoreToolRuntime:
     def __init__(self, output_dir: Path, *, title: str = "",
                  extra_tools: Optional[Sequence[Any]] = None, extra_executor=None,
                  security_config: Any = None, agent_role: str = "") -> None:
+        """Bọc bộ tool của ``core/`` vào cổng ``ToolRuntimePort``.
+
+        Tên các tool phụ được gom sẵn vào một ``set`` ngay tại đây: mỗi lượt gọi tool
+        đều phải tra tên, tra trên danh sách sẽ chậm dần theo số tool.
+        """
         self._output_dir = Path(output_dir)
         self._title = title
         self._extra_tools = list(extra_tools or ())
@@ -80,6 +87,7 @@ class CoreToolRuntime:
     # -- the configured extra tools, for the system-prompt hints ---------- #
     @property
     def extra_names(self) -> frozenset:
+        """Tên các tool bổ sung (MCP, connector) ngoài bộ dựng sẵn."""
         return frozenset(self._extra_names)
 
     def _tool_context(self):
@@ -206,6 +214,7 @@ class CoreToolRuntime:
                 "plan_steps": [PlanStep(title=s["title"], status=s["status"]) for s in steps]}
 
     def snapshot(self) -> Any:
+        """Ảnh chụp thư mục kết quả trước lượt chạy — dùng để biết tệp nào mới sinh ra."""
         from ...core.tools import _snapshot
 
         return _snapshot(self._output_dir)
@@ -294,16 +303,19 @@ def build_cowork_conversation_service(
         _apply_project_context(messages, project_context)
 
     def prompt_guard(messages: List[Dict[str, Any]]) -> None:
+        """Chốt an toàn cho prompt trước khi gửi: quét dấu hiệu tiêm lệnh."""
         from ...core import agent_security
 
         agent_security.enforce_prompt(provider, messages, security_config, emit)
 
     def command_guard(name: str, args: Dict[str, Any]) -> None:
+        """Chốt an toàn cho lệnh shell trước khi chạy: phân loại rủi ro và chặn/hỏi."""
         from ...core import agent_security
 
         agent_security.enforce_command(provider, name, args, security_config, emit)
 
     def compact(messages: List[Dict[str, Any]], cancel) -> None:
+        """Nén lịch sử hội thoại khi gần đầy cửa sổ ngữ cảnh."""
         from ...core import context_budget
 
         context_budget.maybe_compact(provider, messages, security_config,
diff --git a/application/conversations/tool_policy_gateway.py b/application/conversations/tool_policy_gateway.py
index 7d60ffd..6c66295 100644
--- a/application/conversations/tool_policy_gateway.py
+++ b/application/conversations/tool_policy_gateway.py
@@ -39,7 +39,10 @@ from cowork_local.domain.tools import ToolCapability, ToolRegistry
 class ConfirmGate(Protocol):
     """Shape of the existing ``PermissionGate`` both engines already use."""
 
-    def request(self, payload: Dict[str, Any]) -> bool: ...
+    """Hỏi người dùng; trả về ``True`` nếu được đồng ý."""
+    def request(self, payload: Dict[str, Any]) -> bool:
+        """Hỏi người dùng về một lời gọi tool; trả về ``True`` nếu được đồng ý."""
+        ...
 
 
 class ToolPolicyGateway:
@@ -54,6 +57,11 @@ class ToolPolicyGateway:
     """
 
     def __init__(self, registry: ToolRegistry, gated_capabilities: ToolCapability) -> None:
+        """Nhận sổ đăng ký tool và tập năng lực cần xin phép.
+
+        Truyền vào chứ không viết cứng: mỗi bề mặt chat có ngưỡng riêng, và test đặt
+        được ngưỡng của mình mà không đụng cấu hình thật.
+        """
         self._registry = registry
         self._gated_capabilities = gated_capabilities
 
diff --git a/application/model_routing/core_routing_adapter.py b/application/model_routing/core_routing_adapter.py
index f2fdfa8..4e4afd9 100644
--- a/application/model_routing/core_routing_adapter.py
+++ b/application/model_routing/core_routing_adapter.py
@@ -33,6 +33,7 @@ class CoreRoutingEngine:
     """
 
     def __init__(self, routing_service: Any) -> None:
+        """Bọc ``core/routing/service.py`` vào cổng quyết định định tuyến."""
         self._routing_service = routing_service
 
     def evaluate(self, request: RoutingRequest, mode: RoutingMode) -> RouteEvaluation:
@@ -126,6 +127,9 @@ class AppContextModeResolver:
     """
 
     def __init__(self, ctx: Any) -> None:
+        """Đọc chế độ định tuyến từ ``AppContext``, để tầng application không phải biết
+        hình dạng của context.
+        """
         self._ctx = ctx
 
     def mode_for(self, surface: str) -> RoutingMode:
diff --git a/application/model_routing/routing_application_service.py b/application/model_routing/routing_application_service.py
index 9faf703..6db95a6 100644
--- a/application/model_routing/routing_application_service.py
+++ b/application/model_routing/routing_application_service.py
@@ -78,6 +78,10 @@ class RoutingApplicationService:
         *,
         confirm_timeout_sec: Optional[Callable[[], float]] = None,
     ) -> None:
+        """``mode_resolver`` để None thì mọi bề mặt đều coi như đang ở chế độ mặc định.
+        ``confirm_timeout_sec`` là hàm chứ không phải số: người dùng đổi thiết lập
+        giữa chừng thì lần hỏi sau phải theo giá trị mới.
+        """
         self._decision_port = decision_port
         self._mode_resolver = mode_resolver
         # A callable rather than a number: the timeout lives in mutable config
diff --git a/application/monitoring/dashboard_query_service.py b/application/monitoring/dashboard_query_service.py
index 4a5194d..9de2971 100644
--- a/application/monitoring/dashboard_query_service.py
+++ b/application/monitoring/dashboard_query_service.py
@@ -32,6 +32,9 @@ class DashboardQueryService:
     """
 
     def __init__(self, ctx: Any, directory: Optional[Path] = None) -> None:
+        """``directory`` để None thì đọc thư mục telemetry mặc định; test trỏ nó vào
+        ``tmp_path`` để không chạm dữ liệu thật.
+        """
         self.ctx = ctx
         self._directory = directory
 
@@ -94,16 +97,21 @@ class DashboardQueryService:
         return ut.period_totals(events, granularity, self.pricing(), offset)
 
     def period_range_label(self, granularity: str, offset: int) -> str:
+        """Nhãn hiển thị của một kỳ (tuần/tháng/năm cộng độ lệch)."""
         from cowork_local.core import usage_tracker as ut
 
         return ut.period_range_label(granularity, offset)
 
     def budget_status(self):
+        """Tình trạng ngân sách: đã dùng bao nhiêu, còn lại bao nhiêu, có vượt ngưỡng chưa."""
         from cowork_local.core import usage_tracker as ut
 
         return ut.budget_status(self.ctx.config)
 
     def set_budget(self, amount: float, currency: str) -> None:
+        """Đặt hạn mức ngân sách mới — mở một chu kỳ đếm mới, chi tiêu trước đó không
+        còn được tính vào.
+        """
         from cowork_local.core import usage_tracker as ut
 
         ut.set_budget(self.ctx.config, amount, currency)
diff --git a/application/monitoring/dto/__init__.py b/application/monitoring/dto/__init__.py
index e69de29..d81abbf 100644
--- a/application/monitoring/dto/__init__.py
+++ b/application/monitoring/dto/__init__.py
@@ -0,0 +1,3 @@
+"""DTO của phân hệ Giám sát: hình dạng dữ liệu mà tầng application trả cho
+giao diện, không phụ thuộc nguồn đọc.
+"""
diff --git a/application/monitoring/dto/audit_event_dto.py b/application/monitoring/dto/audit_event_dto.py
index 31ba1f3..8bd6dca 100644
--- a/application/monitoring/dto/audit_event_dto.py
+++ b/application/monitoring/dto/audit_event_dto.py
@@ -12,6 +12,9 @@ from typing import Any, Dict
 
 @dataclass(frozen=True)
 class AuditEventDTO:
+    """Một sự kiện kiểm toán ở dạng tầng application dùng — không phụ thuộc khuôn
+    lưu trên đĩa, nên đổi định dạng nhật ký không kéo theo sửa giao diện.
+    """
     ts: str
     kind: str
     name: str
@@ -40,6 +43,7 @@ class AuditEventDTO:
         )
 
     def to_dict(self) -> Dict[str, Any]:
+        """Bản ghi dưới dạng dict cho lớp giao diện."""
         return {
             "ts": self.ts, "kind": self.kind, "agent_role": self.agent_role,
             "name": self.name, "ok": self.ok, "detail": self.detail,
diff --git a/application/monitoring/monitoring_query_service.py b/application/monitoring/monitoring_query_service.py
index 0024f7e..1a35451 100644
--- a/application/monitoring/monitoring_query_service.py
+++ b/application/monitoring/monitoring_query_service.py
@@ -16,6 +16,7 @@ from .repository.audit_event_repository import AuditEventRepository
 
 @dataclass(frozen=True)
 class Page:
+    """Một trang kết quả truy vấn nhật ký: các mục, tổng số, số trang và cỡ trang."""
     items: List[AuditEventDTO]
     total: int
     page: int
@@ -23,6 +24,7 @@ class Page:
 
     @property
     def has_more(self) -> bool:
+        """Còn trang sau nữa không."""
         return self.page * self.page_size < self.total
 
 
@@ -31,11 +33,15 @@ class MonitoringQueryService:
     audit log; this service never writes anything."""
 
     def __init__(self, repository: AuditEventRepository) -> None:
+        """Nhận kho sự kiện kiểm toán qua tham số — bản thật đọc đĩa, bản test nằm
+        trong bộ nhớ.
+        """
         self._repository = repository
 
     def query(self, kind: Optional[str] = None, ok: Optional[bool] = None,
               text: Optional[str] = None, sort_by: str = "ts",
               descending: bool = True, page: int = 1, page_size: int = 50) -> Page:
+        """Lọc theo loại/kết quả/từ khoá, sắp xếp rồi cắt thành một trang."""
         events = self._repository.load(kind=kind)
 
         if ok is not None:
diff --git a/application/monitoring/repository/__init__.py b/application/monitoring/repository/__init__.py
index e69de29..099e195 100644
--- a/application/monitoring/repository/__init__.py
+++ b/application/monitoring/repository/__init__.py
@@ -0,0 +1 @@
+"""Cổng đọc dữ liệu của phân hệ Giám sát — hợp đồng, không phải cài đặt."""
diff --git a/application/monitoring/repository/audit_event_repository.py b/application/monitoring/repository/audit_event_repository.py
index a08492c..81fe1d7 100644
--- a/application/monitoring/repository/audit_event_repository.py
+++ b/application/monitoring/repository/audit_event_repository.py
@@ -13,7 +13,13 @@ from ..dto.audit_event_dto import AuditEventDTO
 
 
 class AuditEventRepository(Protocol):
+    """Cổng đọc nhật ký kiểm toán mà tầng application dùng.
+
+    Chỉ là hợp đồng: bản cài đặt thật đọc từ file cục bộ hoặc thư mục chia sẻ,
+    còn test truyền vào bộ giả.
+    """
     def load(self, kind: Optional[str] = None) -> List[AuditEventDTO]:
+        """Đọc sự kiện kiểm toán, lọc theo loại nếu có."""
         ...
 
 
@@ -22,9 +28,11 @@ class CanonicalAuditEventRepository:
     — the only place this application service reaches into infrastructure."""
 
     def __init__(self, audit_logger) -> None:
+        """Bọc bộ ghi nhật ký kiểm toán chuẩn để đọc sự kiện ra."""
         self._audit_logger = audit_logger
 
     def load(self, kind: Optional[str] = None) -> List[AuditEventDTO]:
+        """Đọc sự kiện từ nhật ký và đổi sang DTO của tầng application."""
         events = self._audit_logger.load_events(kind=kind)
         return [AuditEventDTO.from_raw(e.to_dict()) for e in events]
 
@@ -33,9 +41,13 @@ class InMemoryAuditEventRepository:
     """Test double — holds a fixed list of events, no file I/O."""
 
     def __init__(self, events: List[AuditEventDTO]) -> None:
+        """Nhận sẵn danh sách sự kiện. Chép lại chứ không giữ tham chiếu: bên gọi sửa
+        danh sách gốc thì kết quả test không được đổi theo.
+        """
         self._events = list(events)
 
     def load(self, kind: Optional[str] = None) -> List[AuditEventDTO]:
+        """Trả về danh sách đã nạp sẵn, lọc theo loại nếu có."""
         if kind is None:
             return list(self._events)
         return [e for e in self._events if e.kind == kind]
diff --git a/application/scheduling/ai_task_planner_service.py b/application/scheduling/ai_task_planner_service.py
index 6fbf15e..4371f7d 100644
--- a/application/scheduling/ai_task_planner_service.py
+++ b/application/scheduling/ai_task_planner_service.py
@@ -43,6 +43,9 @@ class AiTaskPlannerService:
     """
 
     def __init__(self, provider_factory: Optional[ProviderFactory] = None) -> None:
+        """``provider_factory`` là hàm dựng provider, gọi lúc cần chứ không dựng sẵn —
+        provider có thể bị đổi giữa hai lần lập kế hoạch.
+        """
         self._provider_factory = provider_factory
 
     def plan(
@@ -86,6 +89,9 @@ class AiTaskPlannerService:
         return import_tasks(path)
 
     def _resolve_provider(self) -> Any:
+        """Provider dùng để lập kế hoạch; chưa cấu hình thì báo lỗi rõ ràng ngay tại
+        đây thay vì để lỗi nổ ra ở tận tầng HTTP.
+        """
         if self._provider_factory is None:
             raise RuntimeError("No provider available to plan tasks.")
         return self._provider_factory()
diff --git a/application/scheduling/task_application_service.py b/application/scheduling/task_application_service.py
index d96c28d..cd62a85 100644
--- a/application/scheduling/task_application_service.py
+++ b/application/scheduling/task_application_service.py
@@ -75,6 +75,9 @@ class TaskApplicationService:
     """
 
     def __init__(self, repository: Any, run_now: Optional[RunNowFn] = None) -> None:
+        """``run_now`` để None thì service chỉ đọc/ghi task, không chạy được cái nào —
+        đúng cho ngữ cảnh không có scheduler (test, hay màn chỉ xem).
+        """
         self._repository = repository
         self._run_now = run_now
 
@@ -118,6 +121,7 @@ class TaskApplicationService:
         return task
 
     def delete(self, task_id: str) -> bool:
+        """Xoá một task; trả về ``False`` nếu id không tồn tại."""
         if self._repository.get(task_id) is None:
             return False
         self._repository.delete(task_id)
diff --git a/application/workflows/co4e_run_history.py b/application/workflows/co4e_run_history.py
new file mode 100644
index 0000000..606b036
--- /dev/null
+++ b/application/workflows/co4e_run_history.py
@@ -0,0 +1,99 @@
+"""Đọc/ghi file lịch sử run của Co4E — tách khỏi ``co4e_workflow_service.py``.
+
+``Co4EWorkflowService`` lo vòng đời các run đang chạy; chỗ này lo đúng một
+việc: đưa ``RunRecord`` ra đĩa và lấy lại được. Tách ra vì hành vi đọc/ghi ở
+đây có những ràng buộc rất riêng — được ghi lại nguyên vẹn bên dưới — mà trộn
+lẫn vào file điều phối thì không ai đọc tới.
+
+DTO ở ``domain/workflows/run_record.py`` không được chạm đĩa, nên việc này
+nằm ở tầng application chứ không nằm trong domain.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from ...domain.workflows.run_record import RunRecord
+from ...infrastructure.persistence.json.atomic_json_file import AtomicJsonFile
+
+#: Giữ N run gần nhất trên đĩa. Lịch sử chỉ để người dùng nhìn lại, không
+#: phải sổ kiểm toán — để nó lớn vô hạn thì mỗi lần lưu lại phải tuần tự hoá
+#: cả file, và lần lưu ấy nằm ngay trên đường đi của mọi sự kiện tiến độ.
+HISTORY_CAP = 500
+
+
+class RunHistoryStore:
+    """Một file JSON chứa lịch sử run, kèm hai quy ước phải giữ nguyên.
+
+    **Không cách ly file hỏng.** Bản đầu dùng ``AtomicJsonFile.read()``, nhưng
+    review thấy nó đổi hành vi thật so với ``Co4ERunManager`` cũ: gặp JSON
+    hỏng, ``AtomicJsonFile.read()`` ĐỔI TÊN file thành ``<tên>.bad-<mốc>`` rồi
+    mới trả về mặc định, trong khi bản cũ chỉ bắt lỗi và ĐỂ NGUYÊN file tại
+    chỗ. Đó là thay đổi quan sát được trên đĩa mà không test nào khoá lại và
+    không có chú thích báo trước — Lâm (N3) quyết ngày 24/08: giữ hành vi cũ.
+    Vì thế :meth:`load` đọc thủ công bằng ``json.loads``.
+
+    **Ghi hỏng không được làm vỡ luồng gọi.** :meth:`save` nuốt ``OSError``,
+    đúng như ``core/co4e_run_manager.py::_save_history``. Nó nằm trên đường đi
+    của mọi hook tiến độ (``_on_event``/``_on_finished``/``_on_failed``); để
+    lỗi ghi đĩa (đầy đĩa, mất quyền) ném ra là vỡ cả lượt xử lý sự kiện đang
+    chạy, chỉ vì lịch sử lần này không lưu được. Người dùng vẫn thấy Flow
+    Status đúng trong phiên hiện tại, chỉ là bản ghi trên đĩa lùi một bước.
+
+    Ghi thì vẫn qua ``AtomicJsonFile``: bản tự viết bằng tmp + ``replace``
+    thiếu ``fsync`` (dữ liệu có thể còn trong bộ đệm khi mất điện) và
+    ``Path.replace`` thỉnh thoảng bị Defender từ chối trên Windows.
+    """
+
+    def __init__(self, path: Path):
+        """Trỏ vào một file JSON. Chưa tồn tại cũng không sao — :meth:`load` coi như
+        lịch sử rỗng và :meth:`save` tự tạo thư mục cha.
+        """
+        self.path = Path(path)
+
+    def load(self) -> Tuple[Dict[str, RunRecord], int]:
+        """Đọc lịch sử; trả về ``({id: RunRecord}, số thứ tự lớn nhất đã dùng)``.
+
+        Số thứ tự trả kèm để bên gọi sinh id tiếp theo không đụng vào id đã có
+        trong lịch sử — không có nó thì sau mỗi lần khởi động lại, ``run1``
+        mới sẽ ghi đè ``run1`` cũ.
+
+        File không có, không đọc được, hay JSON hỏng đều trả về rỗng: mất lịch
+        sử là chuyện chấp nhận được, chặn ứng dụng khởi động thì không. Từng
+        bản ghi hỏng cũng bị bỏ riêng lẻ, để một dòng lỗi không kéo theo cả
+        file.
+        """
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}, 0
+
+        runs: Dict[str, RunRecord] = {}
+        max_seq = 0
+        for rec in data.get("runs", []):
+            try:
+                record = RunRecord.from_dict(rec)
+            except Exception:
+                continue
+            if not record.id:
+                continue
+            runs[record.id] = record
+            if record.id.startswith("run") and record.id[3:].isdigit():
+                max_seq = max(max_seq, int(record.id[3:]))
+        return runs, max_seq
+
+    def save(self, runs: List[RunRecord]) -> None:
+        """Ghi ``HISTORY_CAP`` run gần nhất xuống đĩa, ghi nguyên tử.
+
+        Lỗi ghi bị nuốt có chủ ý — xem docstring của lớp.
+        """
+        payload = {"runs": [r.to_dict() for r in runs[-HISTORY_CAP:]]}
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            AtomicJsonFile(self.path).write(payload)
+        except OSError:
+            pass
+
+
+__all__ = ["RunHistoryStore", "HISTORY_CAP"]
diff --git a/application/workflows/co4e_workflow_service.py b/application/workflows/co4e_workflow_service.py
index 3b2d3cb..d2b0c70 100644
--- a/application/workflows/co4e_workflow_service.py
+++ b/application/workflows/co4e_workflow_service.py
@@ -32,12 +32,20 @@ Qt thật (bọc ``AgentWorker`` — xem ``core/worker.py``) là việc của wi
 KHÔNG xoá/sửa ``core/co4e_run_manager.py`` — lớp cũ tiếp tục chạy song song
 cho tới khi widget Co4E Studio thật (``ui/co4e_tab.py``) chuyển hẳn sang dùng
 service này.
+
+SEAM · dựng 2026-08-25 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``ui/co4e_tab.py`` bỏ ``Co4ERunManager`` và nhận service này qua ``build_co4e_tab(ctx, workflow_service)``.
+Để dormant thì sao: Hai bản cùng giữ vòng đời run đang chạy song song. Càng
+để lâu thì sửa một lỗi lại phải sửa hai nơi — và đến một lúc sẽ có người
+quên nơi thứ hai.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
-from ...infrastructure.persistence.json.atomic_json_file import AtomicJsonFile
-
-import json
 import os
 from datetime import datetime
 from pathlib import Path
@@ -45,12 +53,13 @@ from typing import Callable, Dict, List, Optional, Protocol, Set
 
 from ...core.co4e import CO4E_DIR, STEP_DONE, STEP_ERROR, STEP_PLANNED, Workflow, slugify, workflow_to_dict
 from ...domain.workflows.run_record import RunRecord
+from .co4e_run_history import RunHistoryStore
 
 _TERMINAL_NODE = {STEP_DONE, STEP_ERROR, STEP_PLANNED}
-_HISTORY_CAP = 500          # giữ N run gần nhất trên đĩa
 
 
 def _now_str() -> str:
+    """Mốc thời gian hiện tại dạng 'YYYY-MM-DD HH:MM' — đúng định dạng lịch sử run đang lưu."""
     return datetime.now().strftime("%Y-%m-%d %H:%M")
 
 
@@ -70,15 +79,24 @@ class RunnerJob(Protocol):
     đồng bộ trong test.
     """
 
-    def emit_event(self, ev: dict) -> None: ...
-    def is_cancelled(self) -> bool: ...
+    def emit_event(self, ev: dict) -> None:
+        """Đẩy một sự kiện tiến độ từ luồng nền về service."""
+        ...
+
+    def is_cancelled(self) -> bool:
+        """``True`` khi người dùng đã bấm dừng — thân job phải tự kiểm để thoát sớm."""
+        ...
 
 
 class RunWorkerHandle(Protocol):
     """Điều khiển một job đang chạy nền — tương ứng phần
     ``AgentWorker.request_stop()`` cũ mà ``Co4ERunManager.stop()`` gọi."""
 
-    def request_stop(self) -> None: ...
+    def request_stop(self) -> None:
+        """Xin dừng run. Chỉ là yêu cầu: job đang chạy phải tự thấy qua
+        ``is_cancelled()`` rồi thoát, không ai giết luồng giữa chừng.
+        """
+        ...
 
 
 class WorkflowRunner(Protocol):
@@ -94,7 +112,9 @@ class WorkflowRunner(Protocol):
     def start(self, run_id: str, job: Callable[[RunnerJob], Optional[dict]],
               on_event: Callable[[dict], None],
               on_finished: Callable[[Optional[dict]], None],
-              on_failed: Callable[[str], None]) -> RunWorkerHandle: ...
+              on_failed: Callable[[str], None]) -> RunWorkerHandle:
+        """Chạy ``job`` và trả về tay cầm để dừng nó."""
+        ...
 
 
 class Co4EWorkflowService:
@@ -108,6 +128,12 @@ class Co4EWorkflowService:
 
     def __init__(self, ctx, *, history_path: Optional[Path] = None,
                  runner: Optional[WorkflowRunner] = None):
+        """Dựng service.
+
+        ``runner`` để None nghĩa là chưa có ai chạy được run — đúng trạng thái hiện
+        nay, vì adapter Qt thật thuộc về tầng ``presentation/`` và chưa được nối.
+        Test tiêm runner chạy đồng bộ vào đây.
+        """
         self.ctx = ctx
         self._runs: Dict[str, RunRecord] = {}
         self._worker_handles: Dict[str, RunWorkerHandle] = {}
@@ -116,10 +142,12 @@ class Co4EWorkflowService:
         self._project_id: str = ""                 # workspace đang chọn — Flow Status lọc theo no
         self._runner = runner
         # DTO domain khong duoc cham dia (xem domain/workflows/run_record.py),
-        # nen viec doc/ghi file lich su nam o day, tang application.
+        # nen viec doc/ghi file lich su nam o tang application — cu the la
+        # co4e_run_history.py::RunHistoryStore.
         self._history_path_value = (
             Path(history_path) if history_path is not None else (CO4E_DIR / "run_history.json")
         )
+        self._history = RunHistoryStore(self._history_path_value)
         self._changed_callbacks: List[Callable[[], None]] = []
         self._event_callbacks: List[Callable[[str, dict], None]] = []
         self._load_history()          # khoi phuc lich su cu de Flow Status
@@ -127,71 +155,42 @@ class Co4EWorkflowService:
 
     # ---- callback thay Signal ---------------------------------------------
     def on_changed(self, cb: Callable[[], None]) -> None:
+        """Đăng ký callback gọi mỗi khi danh sách run đổi — thay cho signal Qt cũ."""
         self._changed_callbacks.append(cb)
 
     def on_event(self, cb: Callable[[str, dict], None]) -> None:
+        """Đăng ký callback nhận sự kiện tiến độ của từng run — thay cho signal Qt cũ."""
         self._event_callbacks.append(cb)
 
     def _emit_changed(self) -> None:
+        """Lưu lịch sử rồi báo mọi người đăng ký."""
         self._save_history()          # xem docstring dau file: giu dung thu tu ban Qt cu
         for cb in self._changed_callbacks:
             cb()
 
     def _emit_event(self, run_id: str, ev) -> None:
+        """Chuyển một sự kiện tiến độ tới mọi callback đã đăng ký."""
         for cb in self._event_callbacks:
             cb(run_id, ev)
 
     # ---- persistence --------------------------------------------------
-    # Doc/ghi thu cong (json.loads/write_text + tmp.replace), KHONG dung
-    # AtomicJsonFile — ban dau file nay dung AtomicJsonFile.read(), nhung
-    # review phat hien no doi hanh vi that so voi Co4ERunManager cu: gap
-    # JSON hong, AtomicJsonFile.read() ĐOI TEN file hong thanh
-    # "<ten>.bad-<timestamp>" (quarantine) roi moi tra ve mac dinh, trong
-    # khi ban cu chi bat loi va ĐE NGUYEN file hong tai cho, khong dong gi
-    # vao no. Day la mot thay doi quan sat duoc tren dia ma khong test nao
-    # khoa lai va khong co comment bao truoc — Lam (N3) da quyet 24/08:
-    # GIU HANH VI CU nguyen van (khong quarantine), vi day la buoc tach
-    # chi duoc phep doi hanh vi khi da noi ra ro rang va co lưới an toan,
-    # khong phai luc nay.
     def _load_history(self) -> None:
-        try:
-            data = json.loads(self._history_path_value.read_text(encoding="utf-8"))
-        except (OSError, ValueError):
-            return
-        max_seq = 0
-        for rec in data.get("runs", []):
-            try:
-                record = RunRecord.from_dict(rec)
-            except Exception:
-                continue
-            if not record.id:
-                continue
-            self._runs[record.id] = record
-            if record.id.startswith("run") and record.id[3:].isdigit():
-                max_seq = max(max_seq, int(record.id[3:]))
-        self._seq = max_seq           # tranh sinh id trung voi lich su
+        """Khôi phục lịch sử run từ đĩa lúc khởi động.
+
+        Lấy luôn số thứ tự lớn nhất đã dùng để ``_next_id()`` không sinh trùng
+        id với run cũ.
+        """
+        self._runs, self._seq = self._history.load()
 
     def _save_history(self) -> None:
-        runs = list(self._runs.values())[-_HISTORY_CAP:]
-        payload = {"runs": [r.to_dict() for r in runs]}
-        try:
-            self._history_path_value.parent.mkdir(parents=True, exist_ok=True)
-            # AtomicJsonFile thay cho tmp+replace tự viết: bản cũ thiếu fsync
-            # (dữ liệu có thể còn trong bộ đệm khi mất điện) và dùng thẳng
-            # Path.replace, vốn thỉnh thoảng bị Defender từ chối trên Windows.
-            AtomicJsonFile(self._history_path_value).write(payload)
-        except OSError:
-            # Giu dung hanh vi cu (core/co4e_run_manager.py::_save_history):
-            # mot lan luu that bai (day dia, mat quyen...) KHONG duoc phep
-            # chan luong goi cua moi hook (_on_event/_on_finished/_on_failed)
-            # dang di qua _emit_changed(). Bo try/except nay se lam mot loi
-            # ghi dia lam vo ca luot xu ly su kien dang chay, chi vi lich su
-            # khong luu duoc lan nay -- nguoi dung van thay Flow Status dung
-            # trong phien hien tai, chi la ban ghi tren dia lui lai mot buoc.
-            pass
+        """Ghi lịch sử xuống đĩa. Lỗi ghi bị nuốt có chủ ý — xem
+        ``co4e_run_history.py::RunHistoryStore``.
+        """
+        self._history.save(list(self._runs.values()))
 
     # ---- lifecycle ----------------------------------------------------
     def _next_id(self) -> str:
+        """Sinh id run kế tiếp ('run1', 'run2', ...), không đụng id đã có trong lịch sử."""
         self._seq += 1
         return f"run{self._seq}"
 
@@ -247,6 +246,7 @@ class Co4EWorkflowService:
 
     # ---- worker callbacks (goi tu runner, thay slot Qt cu) -----------------
     def _on_event(self, run_id: str, ev) -> None:
+        """Nhận sự kiện từ job đang chạy và cập nhật bản ghi run."""
         record = self._runs.get(run_id)
         if record is not None and isinstance(ev, dict):
             t = ev.get("type")
@@ -271,6 +271,7 @@ class Co4EWorkflowService:
         self._emit_event(run_id, ev)
 
     def _on_finished(self, run_id: str) -> None:
+        """Job kết thúc mà không phát ``run_done``: chốt trạng thái về 'done'."""
         record = self._runs.get(run_id)
         if record is not None and record.status == "running":
             # job returned without a run_done event (shouldn't happen) — settle it
@@ -278,6 +279,7 @@ class Co4EWorkflowService:
             self._emit_changed()
 
     def _on_failed(self, run_id: str, err: str) -> None:
+        """Job ném lỗi: ghi lỗi vào bản ghi và báo ra ngoài một sự kiện ``run_error``."""
         record = self._runs.get(run_id)
         if record is not None:
             record.status = "error"
@@ -287,6 +289,7 @@ class Co4EWorkflowService:
 
     # ---- control --------------------------------------------------------
     def stop(self, run_id: str) -> None:
+        """Yêu cầu dừng một run đang chạy và đánh dấu 'stopped'."""
         record = self._runs.get(run_id)
         worker = self._worker_handles.get(run_id)
         if record is not None and worker is not None and record.running:
@@ -295,6 +298,7 @@ class Co4EWorkflowService:
             self._emit_changed()
 
     def stop_all(self) -> None:
+        """Dừng mọi run của workspace đang chọn (Flow Status vốn lọc theo project)."""
         # Only the CURRENT workspace's runs (Flow Status is per-project).
         for run_id in [r for r, rec in self._runs.items() if self._belongs(rec)]:
             self.stop(run_id)
@@ -315,6 +319,7 @@ class Co4EWorkflowService:
         self._emit_changed()
 
     def remove(self, run_id: str) -> None:
+        """Xoá một run khỏi lịch sử; đang chạy thì dừng trước."""
         record = self._runs.get(run_id)
         if record is not None and record.running:
             self.stop(run_id)
@@ -323,6 +328,7 @@ class Co4EWorkflowService:
         self._emit_changed()
 
     def clear_finished(self) -> None:
+        """Xoá mọi run đã kết thúc của workspace đang chọn, giữ nguyên run đang chạy."""
         # Only clear finished runs of the CURRENT workspace.
         for run_id in [r for r, rec in self._runs.items() if not rec.running and self._belongs(rec)]:
             self._runs.pop(run_id, None)
@@ -343,9 +349,11 @@ class Co4EWorkflowService:
         return list(self._runs.values())
 
     def get(self, run_id: str) -> Optional[RunRecord]:
+        """Lấy một run theo id; ``None`` nếu không có."""
         return self._runs.get(run_id)
 
     def active_count(self) -> int:
+        """Số run đang chạy của workspace đang chọn — dùng cho huy hiệu trên tab."""
         return sum(1 for r in self._runs.values() if r.running and self._belongs(r))
 
     def set_current_project(self, project_id: str) -> None:
@@ -363,6 +371,7 @@ class Co4EWorkflowService:
         self._output_root = Path(root) if root else None
 
     def _out_dir(self, wf: Workflow) -> Path:
+        """Thư mục ghi kết quả của một luồng, tạo sẵn nếu chưa có."""
         # Flow deliverables are written into the SELECTED workspace (the active
         # project's folder) so they land where the user works with files (Folder
         # tab), not in the config/install folder. One subfolder per flow keeps
diff --git a/application/workspaces/file_preview_helpers.py b/application/workspaces/file_preview_helpers.py
index 393395a..3f1c78f 100644
--- a/application/workspaces/file_preview_helpers.py
+++ b/application/workspaces/file_preview_helpers.py
@@ -28,6 +28,9 @@ def pptx_available() -> bool:
 
 
 def read_text(path: str) -> str:
+    """Đọc tệp dạng văn bản, thay ký tự hỏng thay vì ném lỗi; không đọc được thì
+    trả về chuỗi rỗng.
+    """
     try:
         return Path(path).read_text(encoding="utf-8", errors="replace")
     except OSError as exc:
@@ -35,6 +38,11 @@ def read_text(path: str) -> str:
 
 
 def is_probably_text(path: str) -> bool:
+    """Đoán tệp này có phải văn bản không, bằng cách tìm byte NUL trong phần đầu.
+
+    Đoán sai theo hướng "là văn bản" sẽ hiện một màn hình ký tự rác, nên phép
+    thử cố tình bảo thủ.
+    """
     try:
         with open(path, "rb") as f:
             chunk = f.read(4096)
diff --git a/application/workspaces/file_workspace_service.py b/application/workspaces/file_workspace_service.py
index 67ff35e..c4252dd 100644
--- a/application/workspaces/file_workspace_service.py
+++ b/application/workspaces/file_workspace_service.py
@@ -32,6 +32,9 @@ class FileWorkspaceService:
     """
 
     def __init__(self, session) -> None:  # WorkspaceSession - see module docstring
+        """Nhận một ``WorkspaceSession`` — mọi đường dẫn về sau đều bị nó chặn trong
+        phạm vi cho phép.
+        """
         self._session = session
 
     def list_tree(self, rel: str = ".") -> Dict[str, Any]:
diff --git a/config.py b/config.py
index bfdacd4..df36bc3 100644
--- a/config.py
+++ b/config.py
@@ -275,6 +275,11 @@ def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any
 
 
 def _apply_env_overrides(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Cho phép biến môi trường ghi đè cấu hình.
+
+    Dùng khi chạy trong container/CI: đặt endpoint và khoá qua biến môi trường mà
+    không phải sửa file cấu hình.
+    """
     data = copy.deepcopy(data)
     oc = data["providers"]["openai_compat"]
     if os.getenv("OPENAI_API_KEY"):
@@ -361,6 +366,11 @@ class AppConfig(JsonConfigRepository):
     """
 
     def __init__(self, data=None, path: Path = CONFIG_PATH, **kw):
+        """Mở cấu hình từ đĩa, hoặc dựng thẳng từ dict khi truyền ``data``.
+
+        Dạng ``AppConfig(data=..., path=...)`` là để 13 file test dựng cấu hình mà
+        không chạm đĩa; giữ nguyên vì bỏ đi là phải sửa cả 13 file.
+        """
         if data is None:
             super().__init__(Path(path), **kw)
             return
diff --git a/core/accounts.py b/core/accounts.py
index 9c8a212..378e1bf 100644
--- a/core/accounts.py
+++ b/core/accounts.py
@@ -35,6 +35,7 @@ _LAST_LOGIN_PATH = CONFIG_DIR / "last_login.json"
 
 
 def save_last_login(username: str, role: str) -> None:
+    """Nhớ tài khoản đăng nhập gần nhất để lần mở sau điền sẵn."""
     try:
         _LAST_LOGIN_PATH.parent.mkdir(parents=True, exist_ok=True)
         _LAST_LOGIN_PATH.write_text(
@@ -44,6 +45,7 @@ def save_last_login(username: str, role: str) -> None:
 
 
 def load_last_login() -> Optional[Tuple[str, str]]:
+    """Cặp (tên đăng nhập, vai trò) của lần đăng nhập gần nhất; ``None`` nếu chưa có."""
     try:
         data = json.loads(_LAST_LOGIN_PATH.read_text(encoding="utf-8"))
         username, role = data.get("username", ""), data.get("role", "")
@@ -61,6 +63,7 @@ CODE_LENGTH = 12
 
 @dataclass
 class Account:
+    """Một tài khoản người dùng: tên đăng nhập, vai trò, tên hiển thị và nhóm."""
     username: str
     role: str
     display_name: str = ""
@@ -73,6 +76,7 @@ class Account:
 
 
 def accounts_dir(shared_dir: str) -> Path:
+    """Thư mục chứa tài khoản, nằm trong thư mục chia sẻ của đội."""
     return Path(shared_dir).expanduser() / "accounts"
 
 
@@ -93,6 +97,7 @@ def generate_code(existing_codes: Optional[Set[str]] = None) -> str:
 
 
 def save_account(account: Account, directory: Path) -> Path:
+    """Ghi một tài khoản ra ``<username>.json`` (tên file đã được làm sạch)."""
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{_safe_username(account.username)}.json"
     path.write_text(json.dumps(asdict(account), ensure_ascii=False, indent=2), encoding="utf-8")
@@ -100,6 +105,7 @@ def save_account(account: Account, directory: Path) -> Path:
 
 
 def load_account(username: str, directory: Path) -> Optional[Account]:
+    """Đọc một tài khoản theo tên đăng nhập; không có thì trả ``None``."""
     path = directory / f"{_safe_username(username)}.json"
     if not path.exists():
         return None
@@ -112,6 +118,7 @@ def load_account(username: str, directory: Path) -> Optional[Account]:
 
 
 def list_accounts(directory: Path) -> List[Account]:
+    """Liệt kê mọi tài khoản trong thư mục; thư mục chưa có thì trả list rỗng."""
     if not directory.exists():
         return []
     out: List[Account] = []
@@ -124,6 +131,7 @@ def list_accounts(directory: Path) -> List[Account]:
 
 
 def delete_account(username: str, directory: Path) -> bool:
+    """Xoá file tài khoản; trả về ``True`` nếu có file để xoá."""
     path = directory / f"{_safe_username(username)}.json"
     try:
         path.unlink()
@@ -133,6 +141,7 @@ def delete_account(username: str, directory: Path) -> bool:
 
 
 def find_by_username(username: str, directory: Path) -> Optional[Account]:
+    """Bí danh của :func:`load_account`, giữ cho mã cũ gọi theo tên này vẫn chạy."""
     return load_account(username, directory)
 
 
diff --git a/core/admin_agents.py b/core/admin_agents.py
index 30c6d4f..092228f 100644
--- a/core/admin_agents.py
+++ b/core/admin_agents.py
@@ -74,6 +74,7 @@ _KIND_PROMPTS = {
 
 @dataclass
 class AdminAgent:
+    """Một agent chuyên trách do quản trị cấu hình: prompt riêng, provider và model riêng."""
     agent_id: str
     name: str
     task_kind: str = "cowork"
@@ -85,6 +86,9 @@ class AdminAgent:
     updated_by: str = ""
 
     def effective_prompt(self) -> str:
+        """Prompt hệ thống thật sự dùng: prompt mặc định theo loại việc, rồi tới phần
+        quản trị viết thêm.
+        """
         parts = [_KIND_PROMPTS.get(self.task_kind, ""), (self.prompt or "").strip()]
         return "\n\n".join(p for p in parts if p)
 
@@ -98,12 +102,17 @@ def agents_admin_dir(shared_dir: str = "") -> Path:
 
 
 def _slug(name: str) -> str:
+    """Định danh an toàn cho tên file, suy từ tên agent."""
     s = re.sub(r"[^\w\-]+", "-", (name or "").strip().lower()).strip("-")
     return s or "agent"
 
 
 def new_agent(name: str, task_kind: str = "cowork", prompt: str = "",
               provider: str = "", model: str = "", updated_by: str = "") -> AdminAgent:
+    """Tạo một agent quản trị mới; loại việc lạ thì rơi về 'cowork'.
+
+    Id ghép slug với 6 ký tự ngẫu nhiên để hai agent trùng tên không đè file nhau.
+    """
     return AdminAgent(
         agent_id=f"{_slug(name)}-{uuid.uuid4().hex[:6]}",
         name=name.strip(), task_kind=task_kind if task_kind in TASK_KINDS else "cowork",
@@ -113,6 +122,7 @@ def new_agent(name: str, task_kind: str = "cowork", prompt: str = "",
 
 
 def save_agent(agent: AdminAgent, directory: Path) -> Path:
+    """Ghi một agent ra ``<agent_id>.json``."""
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{agent.agent_id}.json"
     path.write_text(json.dumps(asdict(agent), ensure_ascii=False, indent=2), encoding="utf-8")
@@ -120,6 +130,7 @@ def save_agent(agent: AdminAgent, directory: Path) -> Path:
 
 
 def load_agent(agent_id: str, directory: Path) -> Optional[AdminAgent]:
+    """Đọc một agent theo id; không có thì trả ``None``."""
     path = directory / f"{agent_id}.json"
     if not path.exists():
         return None
@@ -132,6 +143,7 @@ def load_agent(agent_id: str, directory: Path) -> Optional[AdminAgent]:
 
 
 def list_agents(directory: Path, enabled_only: bool = False) -> List[AdminAgent]:
+    """Liệt kê agent trong thư mục; ``enabled_only`` chỉ lấy agent đang bật."""
     if not directory.exists():
         return []
     out: List[AdminAgent] = []
@@ -165,6 +177,7 @@ def ensure_help_agent(directory: Path) -> AdminAgent:
 
 
 def delete_agent(agent_id: str, directory: Path) -> bool:
+    """Xoá file agent; trả về ``True`` nếu có file để xoá."""
     try:
         (directory / f"{agent_id}.json").unlink()
         return True
diff --git a/core/agent_command.py b/core/agent_command.py
index d3271b2..5da822f 100644
--- a/core/agent_command.py
+++ b/core/agent_command.py
@@ -31,6 +31,7 @@ _CMD = re.compile(r"(?<!\S)/agent(?::([\w\-.]+))?(?=$|[\s.,;:!?)\]}»”’'\"
 
 
 def _slug(name: str) -> str:
+    """Định danh an toàn suy từ tên agent (dùng chung hàm với Co4E)."""
     from .co4e import slugify
     return slugify(name)
 
@@ -45,6 +46,11 @@ def collect_agents(shared_dir: str = "") -> List[dict]:
     seen: set[str] = set()
 
     def _add(slug: str, name: str, desc: str, persona: str, source: str) -> None:
+        """Thêm một agent vào danh sách gộp; bỏ qua nếu trùng slug hoặc thiếu persona.
+
+        Agent không có persona thì không dùng được — thêm vào chỉ làm bảng gợi ý dài
+        ra mà chọn vào lại không chạy.
+        """
         if not slug or slug in seen or not persona.strip():
             return
         seen.add(slug)
@@ -69,6 +75,7 @@ def collect_agents(shared_dir: str = "") -> List[dict]:
 
 
 def _persona_block(agent: dict) -> str:
+    """Khối prompt mô tả một agent, chèn vào đầu lượt chat khi người dùng gõ ``/agent:``."""
     return f"## Agent: {agent['name']}\n{agent['persona']}"
 
 
diff --git a/core/agent_roles.py b/core/agent_roles.py
index 7f605b4..4e2d6c6 100644
--- a/core/agent_roles.py
+++ b/core/agent_roles.py
@@ -37,6 +37,7 @@ HELP = "help"
 
 
 class AgentRole(NamedTuple):
+    """Một vai trò agent: khoá, nhãn hiển thị và prompt mặc định."""
     key: str
     label: str
     description: str
@@ -61,5 +62,6 @@ ROLES: Dict[str, AgentRole] = {
 
 
 def label_for(role_key: str) -> str:
+    """Nhãn của một vai trò; khoá lạ thì trả về chính khoá, rỗng thì trả về "—"."""
     role = ROLES.get(role_key)
     return role.label if role else (role_key or "—")
diff --git a/core/agent_security.py b/core/agent_security.py
index 917c771..8877301 100644
--- a/core/agent_security.py
+++ b/core/agent_security.py
@@ -149,6 +149,10 @@ def _ai_verdict(provider: Provider, system_prompt: str, content: str, layer: str
 
 
 def validate_prompt(provider: Provider, user_text: str, rules_text: str) -> SecurityVerdict:
+    """Nhờ model xét prompt người dùng theo bộ luật an toàn.
+
+    Prompt rỗng thì cho qua ngay, khỏi tốn một lượt gọi.
+    """
     if not (user_text or "").strip():
         return SecurityVerdict(True, "", "prompt")
     system = _PROMPT_SYSTEM.format(rules=rules_text or "(no additional rules configured)")
@@ -157,6 +161,7 @@ def validate_prompt(provider: Provider, user_text: str, rules_text: str) -> Secu
 
 def validate_attachment(provider: Provider, filename: str, content: str,
                         rules_text: str) -> SecurityVerdict:
+    """Nhờ model xét nội dung một tệp đính kèm theo bộ luật an toàn."""
     if not (content or "").strip():
         return SecurityVerdict(True, "", "attachment")
     system = _ATTACHMENT_SYSTEM.format(rules=rules_text or "(no additional rules configured)")
@@ -165,6 +170,11 @@ def validate_attachment(provider: Provider, filename: str, content: str,
 
 def validate_command(provider: Provider, command: str,
                      rules_text: str, ai_enabled: bool) -> SecurityVerdict:
+    """Nhờ model xét một lệnh shell theo bộ luật an toàn.
+
+    ``ai_enabled=False`` thì cho qua — người dùng đã tắt lớp xét bằng AI, bộ luật
+    tĩnh vẫn chạy ở chỗ khác.
+    """
     if not ai_enabled:
         return SecurityVerdict(True, "", "command")
     system = _COMMAND_SYSTEM.format(rules=rules_text or "(no additional rules configured)")
@@ -173,6 +183,7 @@ def validate_command(provider: Provider, command: str,
 
 # ---- call-site convenience wrappers (used by chat_agent.py / code_agent.py) --
 def _security_conf(config) -> dict:
+    """Nhóm cấu hình ``agent_security``; không có config thì trả dict rỗng."""
     return (config.data.get("agent_security", {}) if config is not None else {})
 
 
diff --git a/core/agent_security_types.py b/core/agent_security_types.py
index 044d01d..af28aab 100644
--- a/core/agent_security_types.py
+++ b/core/agent_security_types.py
@@ -19,6 +19,7 @@ from dataclasses import dataclass
 
 @dataclass
 class SecurityVerdict:
+    """Kết quả một lớp kiểm an toàn: cho qua hay không, lý do, và lớp nào ra phán quyết."""
     allowed: bool
     reason: str = ""
     layer: str = ""   # "prompt" | "attachment" | "command"
@@ -29,5 +30,6 @@ class SecurityBlocked(RuntimeError):
     the admin alert; ``str(exc)`` is the short, user-facing reason."""
 
     def __init__(self, verdict: SecurityVerdict):
+        """Lấy lý do trong phán quyết làm thông điệp; không có lý do thì ghi rõ lớp nào chặn."""
         super().__init__(verdict.reason or f"Blocked by agent security ({verdict.layer}).")
         self.verdict = verdict
diff --git a/core/ai_task_planner.py b/core/ai_task_planner.py
index fe325b1..22bd0a6 100644
--- a/core/ai_task_planner.py
+++ b/core/ai_task_planner.py
@@ -54,6 +54,10 @@ def _extract_json(text: str) -> Optional[dict]:
 
 
 def _clamp(value, allowed, default):
+    """Ép một giá trị về tập hợp lệ; ngoài tập thì lấy mặc định.
+
+    Cần vì model hay trả về giá trị gần đúng ('High' thay vì 'high').
+    """
     return value if value in allowed else default
 
 
diff --git a/core/appcontainer_sandbox.py b/core/appcontainer_sandbox.py
index b872867..3b14ba5 100644
--- a/core/appcontainer_sandbox.py
+++ b/core/appcontainer_sandbox.py
@@ -48,6 +48,7 @@ class AppContainerSandbox:
         display_name: str = "CoworkLocal Sandbox",
         description: str = "Isolated execution environment for Cowork Local agent",
     ):
+        """Đặt tên và mô tả cho hồ sơ AppContainer; chưa tạo gì trên máy."""
         self.profile_name = profile_name
         self.display_name = display_name
         self.description = description
diff --git a/core/chat_agent.py b/core/chat_agent.py
index eaa0917..3b41cb9 100644
--- a/core/chat_agent.py
+++ b/core/chat_agent.py
@@ -135,6 +135,12 @@ _UNSAFE = re.compile(r'[\\/:*?"<>|\x00-\x1f]+')
 
 
 def _safe_filename(name: str) -> str:
+    """Làm sạch tên tệp do model đề xuất: bỏ đường dẫn, thay ký tự cấm, không bao
+    giờ trả về chuỗi rỗng.
+
+    Model hay trả về tên có dấu ``/`` hoặc ``..`` — ghi thẳng là thoát khỏi thư
+    mục làm việc.
+    """
     base = Path(str(name)).name.strip()
     base = _UNSAFE.sub("_", base).strip(" _.") or "output.txt"
     if "." not in base:
@@ -307,17 +313,23 @@ def run_chat(
     emit: EmitFn,
     cancel: Optional[CancelFn] = None,
 ) -> Dict[str, Any]:
+    """Chạy một lượt chat thuần (không có tool) và phát nội dung dần ra ngoài.
+
+    Tự chèn prompt hệ thống nếu tin nhắn đầu chưa phải ``system``.
+    """
     if not messages or messages[0].get("role") != "system":
         messages.insert(0, {"role": "system", "content": COWORK_SYSTEM_PROMPT})
     # Rulebase: always attach security rules so the agent follows them every turn
     _apply_security_rules(messages, load_rules())
 
     def on_text(piece: str) -> None:
+        """Đẩy từng mẩu câu trả lời ra ngoài."""
         emit({"type": "text", "delta": piece})
 
     def on_reasoning(piece: str) -> None:
         # Stream the model's reasoning so the UI can show a live, collapsible
         # "Thinking" box (and keep the indicator active).
+        """Đẩy từng mẩu suy luận nội bộ ra ngoài, để giao diện hiện hộp "Đang nghĩ"."""
         emit({"type": "reasoning", "delta": piece})
 
     assistant = provider.chat(messages, tools=None, on_text=on_text, cancel=cancel,
diff --git a/core/co4e.py b/core/co4e.py
index 46e3682..ff64646 100644
--- a/core/co4e.py
+++ b/core/co4e.py
@@ -54,6 +54,9 @@ RUN_MODES = ("auto", "plan", "manual")
 
 
 def slugify(value: str) -> str:
+    """Chuyển một chuỗi thành slug an toàn cho tên file: chỉ chữ/số/gạch, gộp gạch
+    liên tiếp. Rỗng thì trả về 'step' để không bao giờ sinh ra tên file trống.
+    """
     s = "".join(c if (c.isalnum() or c in "-_") else "-" for c in (value or "").strip().lower())
     return "-".join(filter(None, s.split("-"))) or "step"
 
@@ -88,11 +91,13 @@ class Step:
 
     @property
     def is_parallel(self) -> bool:
+        """Bước này có chạy nhiều sub-agent song song hay không."""
         return self.variant == "parallel"
 
 
 @dataclass
 class Node:
+    """Một node trên khung vẽ: id, toạ độ, và bước (:class:`Step`) mà nó đại diện."""
     id: str
     x: float = 0.0
     y: float = 0.0
@@ -101,6 +106,7 @@ class Node:
 
 @dataclass
 class Edge:
+    """Một cạnh nối hai node, quy định thứ tự chạy giữa chúng."""
     id: str
     source: str
     target: str
@@ -108,6 +114,7 @@ class Edge:
 
 @dataclass
 class Workflow:
+    """Một luồng Co4E: danh sách node, cạnh, và cờ đánh dấu đây có phải mẫu không."""
     id: str
     name: str = "Untitled flow"
     is_template: bool = False
@@ -132,6 +139,10 @@ class CustomAgent:
 
 # ---- (de)serialization ---------------------------------------------------
 def step_from_dict(d: dict) -> Step:
+    """Dựng :class:`Step` từ dict đọc trên đĩa.
+
+    Lọc bỏ khoá lạ để file luồng của phiên bản mới hơn không làm vỡ bản cũ.
+    """
     d = dict(d or {})
     subs = d.pop("sub_agents", None) or []
     known = Step().__dict__.keys()
@@ -145,11 +156,13 @@ def step_from_dict(d: dict) -> Step:
 
 
 def node_from_dict(d: dict) -> Node:
+    """Dựng :class:`Node` từ dict đọc trên đĩa."""
     return Node(id=str(d.get("id", "")), x=float(d.get("x", 0) or 0),
                 y=float(d.get("y", 0) or 0), data=step_from_dict(d.get("data", {})))
 
 
 def workflow_from_dict(d: dict) -> Workflow:
+    """Dựng :class:`Workflow` từ dict đọc trên đĩa."""
     return Workflow(
         id=str(d.get("id", "")),
         name=d.get("name", "Untitled flow"),
@@ -161,6 +174,7 @@ def workflow_from_dict(d: dict) -> Workflow:
 
 
 def workflow_to_dict(wf: Workflow) -> dict:
+    """Chuyển một luồng thành dict để ghi JSON."""
     return {
         "id": wf.id, "name": wf.name, "is_template": wf.is_template,
         "nodes": [{"id": n.id, "x": n.x, "y": n.y, "data": _step_dict(n.data)} for n in wf.nodes],
@@ -169,16 +183,19 @@ def workflow_to_dict(wf: Workflow) -> dict:
 
 
 def _step_dict(step: Step) -> dict:
+    """Chuyển một bước thành dict; ``asdict`` đã tự chuyển ``sub_agents`` thành list dict."""
     d = asdict(step)
     # asdict already turns sub_agents into list[dict]
     return d
 
 
 def agent_to_dict(a: CustomAgent) -> dict:
+    """Chuyển một agent tự tạo thành dict để ghi JSON."""
     return asdict(a)
 
 
 def agent_from_dict(d: dict) -> CustomAgent:
+    """Dựng :class:`CustomAgent` từ dict, lọc bỏ khoá lạ."""
     known = CustomAgent(id="").__dict__.keys()
     d = {k: v for k, v in (d or {}).items() if k in known}
     d.setdefault("id", "")
@@ -193,32 +210,43 @@ _counter = {"n": 0}
 
 
 def _mint_id(prefix: str) -> str:
+    """Sinh id tăng dần dạng ``<prefix>_000001``."""
     _counter["n"] += 1
     return f"{prefix}_{_counter['n']:06d}"
 
 
 def new_node_id() -> str:
+    """Id mới cho một node."""
     return _mint_id("node")
 
 
 def new_edge_id(source: str, target: str) -> str:
+    """Id cạnh suy ra TỪ cặp nguồn/đích.
+
+    Cố ý không ngẫu nhiên: nhờ vậy nối lại đúng cặp node đó luôn cho ra cùng
+    một id, và không thể sinh ra hai cạnh trùng nhau.
+    """
     return f"e_{source}__{target}"
 
 
 def new_workflow(name: str = "Untitled flow") -> Workflow:
+    """Tạo một luồng rỗng với id mới."""
     return Workflow(id=_mint_id("wf"), name=name)
 
 
 def new_custom_agent(name: str = "") -> CustomAgent:
+    """Tạo một agent tự tạo rỗng với id mới."""
     return CustomAgent(id=_mint_id("agent"), name=name)
 
 
 # ---- workflow store ------------------------------------------------------
 def workflows_dir() -> Path:
+    """Thư mục chứa file luồng."""
     return WORKFLOWS_DIR
 
 
 def list_workflows(directory: Optional[Path] = None) -> List[Workflow]:
+    """Liệt kê mọi luồng đã lưu; thư mục chưa có thì trả list rỗng."""
     directory = directory or WORKFLOWS_DIR
     if not directory.exists():
         return []
@@ -232,6 +260,7 @@ def list_workflows(directory: Optional[Path] = None) -> List[Workflow]:
 
 
 def save_workflow(wf: Workflow, directory: Optional[Path] = None) -> Path:
+    """Ghi một luồng ra ``<id>.json``, tự tạo thư mục nếu chưa có."""
     directory = directory or WORKFLOWS_DIR
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{wf.id}.json"
@@ -242,6 +271,7 @@ def save_workflow(wf: Workflow, directory: Optional[Path] = None) -> Path:
 
 
 def get_workflow(wf_id: str, directory: Optional[Path] = None) -> Optional[Workflow]:
+    """Đọc một luồng theo id; ``None`` nếu không có."""
     directory = directory or WORKFLOWS_DIR
     path = directory / f"{wf_id}.json"
     if not path.exists():
@@ -280,6 +310,7 @@ def tr_copy_suffix() -> str:
 
 
 def delete_workflow(wf_id: str, directory: Optional[Path] = None) -> None:
+    """Xoá file luồng theo id; không có thì bỏ qua."""
     directory = directory or WORKFLOWS_DIR
     path = directory / f"{wf_id}.json"
     if path.exists():
@@ -291,10 +322,12 @@ def delete_workflow(wf_id: str, directory: Optional[Path] = None) -> None:
 
 # ---- custom-agent store --------------------------------------------------
 def agents_dir() -> Path:
+    """Thư mục chứa file agent tự tạo."""
     return AGENTS_DIR
 
 
 def list_custom_agents(directory: Optional[Path] = None) -> List[CustomAgent]:
+    """Liệt kê mọi agent tự tạo; thư mục chưa có thì trả list rỗng."""
     directory = directory or AGENTS_DIR
     if not directory.exists():
         return []
@@ -308,6 +341,7 @@ def list_custom_agents(directory: Optional[Path] = None) -> List[CustomAgent]:
 
 
 def save_custom_agent(agent: CustomAgent, directory: Optional[Path] = None) -> Path:
+    """Ghi một agent tự tạo ra ``<id>.json``."""
     directory = directory or AGENTS_DIR
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{agent.id}.json"
@@ -316,6 +350,7 @@ def save_custom_agent(agent: CustomAgent, directory: Optional[Path] = None) -> P
 
 
 def delete_custom_agent(agent_id: str, directory: Optional[Path] = None) -> None:
+    """Xoá file agent tự tạo theo id; không có thì bỏ qua."""
     directory = directory or AGENTS_DIR
     path = directory / f"{agent_id}.json"
     if path.exists():
@@ -340,6 +375,11 @@ def compute_waves(nodes: List[Node], edges: List[Edge]) -> Dict[str, int]:
     limit = len(nodes) + 1
 
     def depth(nid: str, seen: frozenset) -> int:
+        """Độ sâu của một node = lớp chạy của nó.
+
+        Có nhớ kết quả và chặn theo ``limit``: đồ thị có vòng sẽ khiến đệ quy chạy
+        mãi, nên gặp node đã thấy trong nhánh hiện tại thì dừng.
+        """
         if nid in wave:
             return wave[nid]
         if nid in seen or len(seen) > limit:
@@ -360,12 +400,14 @@ def connected_component_count(nodes: List[Node], edges: List[Edge]) -> int:
     parent = {n.id: n.id for n in nodes}
 
     def find(x):
+        """Tìm gốc của một phần tử, kèm nén đường đi (union-find)."""
         while parent[x] != x:
             parent[x] = parent[parent[x]]
             x = parent[x]
         return x
 
     def union(a, b):
+        """Gộp hai tập hợp lại làm một (union-find)."""
         ra, rb = find(a), find(b)
         if ra != rb:
             parent[ra] = rb
@@ -379,6 +421,7 @@ def connected_component_count(nodes: List[Node], edges: List[Edge]) -> int:
 # ---- run-stage compilation ----------------------------------------------
 @dataclass
 class RunStage:
+    """Một chặng chạy: ứng với một node, hoặc một nhánh song song / bước gộp của nó."""
     id: str              # node id, or "<node>__p<i>" / "<node>__pjoin"
     node_id: str         # which canvas node this stage maps back onto
     wave: int
@@ -395,6 +438,7 @@ PLAN_MODE_PREAMBLE = (
 
 
 def build_skills_block(skills: List[str], skill_map: Dict[str, str]) -> str:
+    """Ghép nội dung các skill được chọn thành một khối chèn vào prompt."""
     parts = []
     for name in skills or []:
         content = (skill_map.get(name) or "").strip()
@@ -407,6 +451,9 @@ def build_skills_block(skills: List[str], skill_map: Dict[str, str]) -> str:
 
 
 def _shared_prompt_parts(step: Step, skill_map: Dict[str, str], extra_context: str) -> str:
+    """Phần prompt dùng chung cho cả ba loại chặng: chỉ dẫn của bước, khối skill,
+    và ngữ cảnh thêm từ các bước trước.
+    """
     parts = []
     if step.instructions.strip():
         parts.append(step.instructions.strip())
@@ -423,6 +470,7 @@ def _shared_prompt_parts(step: Step, skill_map: Dict[str, str], extra_context: s
 
 
 def build_step_prompt(step: Step, skill_map: Dict[str, str], extra_context: str = "") -> str:
+    """Prompt cho một bước chạy tuần tự bình thường."""
     head = f'You are the {step.role} agent for the workflow step "{step.label}".'
     body = _shared_prompt_parts(step, skill_map, extra_context)
     return f"{head}\n{body}".strip()
@@ -430,6 +478,11 @@ def build_step_prompt(step: Step, skill_map: Dict[str, str], extra_context: str
 
 def build_subagent_prompt(step: Step, sub: SubAgent, peers: List[str],
                           skill_map: Dict[str, str], extra_context: str = "") -> str:
+    """Prompt cho một sub-agent chạy song song.
+
+    Nói rõ nó đang chạy CÙNG LÚC với những ai và phải ở trong phạm vi của mình —
+    không có câu đó, các sub-agent hay làm chồng việc của nhau.
+    """
     peer_txt = ", ".join(p for p in peers if p) or "peers"
     head = (f'You are the "{sub.agent}" agent working concurrently (in parallel with '
             f'{peer_txt}) on the workflow step "{step.label}". Stay within your own scope.')
@@ -443,6 +496,7 @@ def build_subagent_prompt(step: Step, sub: SubAgent, peers: List[str],
 
 
 def build_join_prompt(step: Step, skill_map: Dict[str, str], extra_context: str = "") -> str:
+    """Prompt cho bước gộp: hợp nhất đầu ra của các sub-agent thành một kết quả."""
     head = (f'You are the coordinator for the parallel step "{step.label}". Consolidate the '
             f"outputs of the sub-agents (provided above as prior outputs) into one coherent result.")
     body = _shared_prompt_parts(step, skill_map, extra_context)
@@ -461,6 +515,9 @@ def compile_run_stages(nodes: List[Node], edges: List[Edge],
     stages: List[RunStage] = []
 
     def finalize(prompt: str, preset: str) -> tuple:
+        """Chốt prompt của một chặng: áp phạm vi theo preset, và thêm lời mở đầu chế
+        độ lập kế hoạch nếu đang chạy ở chế độ đó.
+        """
         scope = PRESET_SCOPES.get(preset)
         if plan_mode:
             prompt = PLAN_MODE_PREAMBLE + prompt
diff --git a/core/co4e_builtins.py b/core/co4e_builtins.py
index 179f849..71b661d 100644
--- a/core/co4e_builtins.py
+++ b/core/co4e_builtins.py
@@ -15,6 +15,7 @@ from .co4e import (
 
 @dataclass
 class BuiltinAgent:
+    """Một agent dựng sẵn của Co4E: slug, tên, vai trò và prompt mặc định."""
     slug: str
     name: str
     role: str
diff --git a/core/co4e_run_manager.py b/core/co4e_run_manager.py
index 1695401..c253daf 100644
--- a/core/co4e_run_manager.py
+++ b/core/co4e_run_manager.py
@@ -28,6 +28,7 @@ _HISTORY_CAP = 500          # keep the most-recent N runs on disk
 
 
 def _now_str() -> str:
+    """Mốc thời gian hiện tại dạng 'YYYY-MM-DD HH:MM' cho lịch sử run."""
     from datetime import datetime
     return datetime.now().strftime("%Y-%m-%d %H:%M")
 
@@ -44,6 +45,11 @@ class RunHandle:
     def __init__(self, run_id: str, wf_id: str, name: str, total: int,
                  plan_mode: bool, manual: bool, created_by: str = "", created_at: str = "",
                  project_id: str = ""):
+        """Một lượt chạy workflow đang sống trong bộ nhớ.
+
+        ``total`` âm bị kẹp về 0 — số bước không thể âm, và để lọt xuống thì thanh
+        tiến độ vẽ ngược.
+        """
         self.id = run_id
         self.wf_id = wf_id
         self.name = name
@@ -64,9 +70,11 @@ class RunHandle:
 
     @property
     def running(self) -> bool:
+        """Lượt chạy này còn đang chạy hay không."""
         return self.status == "running"
 
     def progress_text(self) -> str:
+        """Chuỗi tiến độ 'xong/tổng'; chưa biết tổng thì hiện trạng thái."""
         return f"{self.done}/{self.total}" if self.total else self.status
 
     # ---- persistence ------------------------------------------------------
@@ -87,6 +95,7 @@ class RunHandle:
 
     @classmethod
     def from_record(cls, rec: dict) -> "RunHandle":
+        """Dựng lại một ``RunHandle`` từ bản ghi đọc trong lịch sử trên đĩa."""
         from .co4e import workflow_from_dict
         rec = dict(rec or {})
         h = cls(str(rec.get("id", "")), str(rec.get("wf_id", "")),
@@ -109,10 +118,18 @@ class RunHandle:
 
 
 class Co4ERunManager(QObject):
+    """Quản lý vòng đời nhiều lượt chạy luồng Co4E cùng lúc.
+
+    Flow Status lọc theo project, nên hầu hết truy vấn ở đây chỉ tính run thuộc
+    workspace ĐANG chọn — xem ``_belongs``.
+    """
     changed = Signal()               # any run's status/progress changed → refresh views
     event = Signal(str, dict)        # (run_id, ev) — node-level events, for mirroring
 
     def __init__(self, ctx):
+        """Dựng bộ quản lý run và khôi phục lịch sử cũ ngay, để tab Flow Status có nội
+        dung ngay khi mở chứ không trống cho tới lần chạy đầu tiên.
+        """
         super().__init__()
         self.ctx = ctx
         self._runs: Dict[str, RunHandle] = {}
@@ -126,10 +143,12 @@ class Co4ERunManager(QObject):
 
     # ---- persistence ------------------------------------------------------
     def _history_path(self) -> Path:
+        """Đường dẫn file lịch sử run."""
         from .co4e import CO4E_DIR
         return CO4E_DIR / "run_history.json"
 
     def _load_history(self) -> None:
+        """Khôi phục lịch sử run từ đĩa lúc khởi động; file hỏng thì bỏ qua lặng lẽ."""
         path = self._history_path()
         try:
             data = json.loads(path.read_text(encoding="utf-8"))
@@ -149,6 +168,7 @@ class Co4ERunManager(QObject):
         self._seq = max_seq           # avoid minting ids that collide with history
 
     def _save_history(self) -> None:
+        """Ghi ``_HISTORY_CAP`` run gần nhất xuống đĩa."""
         path = self._history_path()
         runs = list(self._runs.values())[-_HISTORY_CAP:]
         payload = {"runs": [h.to_record() for h in runs]}
@@ -163,6 +183,7 @@ class Co4ERunManager(QObject):
 
     # ---- lifecycle --------------------------------------------------------
     def _next_id(self) -> str:
+        """Sinh id run kế tiếp dạng 'runN'."""
         self._seq += 1
         return f"run{self._seq}"
 
@@ -198,6 +219,7 @@ class Co4ERunManager(QObject):
 
         run_label = handle.name
         def job(worker: AgentWorker):
+            """Chạy nền: thực thi luồng, chuyển tiếp sự kiện tiến độ và cờ huỷ."""
             return co4e_runner.run_workflow(
                 ctx, nodes, edges, out_dir, worker.emit_event, worker.is_cancelled,
                 plan_mode=plan_mode, skill_map=sk, only_nodes=only, seed_outputs=seed,
@@ -215,6 +237,7 @@ class Co4ERunManager(QObject):
 
     # ---- worker callbacks -------------------------------------------------
     def _on_event(self, run_id: str, ev: dict) -> None:
+        """Nhận sự kiện từ luồng đang chạy và cập nhật trạng thái/tiến độ của run."""
         handle = self._runs.get(run_id)
         if handle is not None and isinstance(ev, dict):
             t = ev.get("type")
@@ -229,6 +252,10 @@ class Co4ERunManager(QObject):
         self.event.emit(run_id, ev)
 
     def _on_finished(self, run_id: str) -> None:
+        """Job kết thúc mà không phát ``run_done``: chốt trạng thái về 'done'.
+
+        Lẽ ra không xảy ra, nhưng thiếu bước này thì run kẹt ở 'running' mãi.
+        """
         handle = self._runs.get(run_id)
         if handle is not None and handle.status == "running":
             # job returned without a run_done event (shouldn't happen) — settle it
@@ -236,6 +263,7 @@ class Co4ERunManager(QObject):
             self.changed.emit()
 
     def _on_failed(self, run_id: str, err: str) -> None:
+        """Job ném lỗi: ghi lỗi vào bản ghi run và báo ra ngoài."""
         handle = self._runs.get(run_id)
         if handle is not None:
             handle.status = "error"
@@ -245,6 +273,7 @@ class Co4ERunManager(QObject):
 
     # ---- control ----------------------------------------------------------
     def stop(self, run_id: str) -> None:
+        """Yêu cầu dừng một run đang chạy."""
         handle = self._runs.get(run_id)
         if handle is not None and handle.worker is not None and handle.running:
             handle.worker.request_stop()
@@ -253,6 +282,7 @@ class Co4ERunManager(QObject):
 
     def stop_all(self) -> None:
         # Only the CURRENT workspace's runs (Flow Status is per-project).
+        """Dừng mọi run của workspace đang chọn."""
         for run_id in [r for r, h in self._runs.items() if self._belongs(h)]:
             self.stop(run_id)
 
@@ -269,6 +299,7 @@ class Co4ERunManager(QObject):
         self.changed.emit()
 
     def remove(self, run_id: str) -> None:
+        """Xoá một run khỏi lịch sử; đang chạy thì dừng trước."""
         handle = self._runs.get(run_id)
         if handle is not None and handle.running:
             self.stop(run_id)
@@ -277,6 +308,7 @@ class Co4ERunManager(QObject):
 
     def clear_finished(self) -> None:
         # Only clear finished runs of the CURRENT workspace.
+        """Xoá mọi run đã kết thúc của workspace đang chọn, giữ nguyên run đang chạy."""
         for run_id in [r for r, h in self._runs.items() if not h.running and self._belongs(h)]:
             self._runs.pop(run_id, None)
         self.changed.emit()
@@ -295,9 +327,11 @@ class Co4ERunManager(QObject):
         return list(self._runs.values())
 
     def get(self, run_id: str) -> Optional[RunHandle]:
+        """Bản ghi của một run theo id; ``None`` nếu không có."""
         return self._runs.get(run_id)
 
     def active_count(self) -> int:
+        """Số run đang chạy của workspace đang chọn."""
         return sum(1 for h in self._runs.values() if h.running and self._belongs(h))
 
     def set_current_project(self, project_id: str) -> None:
@@ -320,6 +354,11 @@ class Co4ERunManager(QObject):
         # tab), not in the config/install folder. One subfolder per flow keeps
         # runs tidy. Falls back to the global Cowork output dir when no workspace
         # is selected.
+        """Thư mục ghi kết quả của một luồng, tạo sẵn nếu chưa có.
+
+        Ưu tiên thư mục của workspace đang chọn để file rơi đúng chỗ người dùng làm
+        việc (màn Thư mục), không rơi vào thư mục cài đặt.
+        """
         from .co4e import slugify
         base = self._output_root
         if base is None:
diff --git a/core/co4e_runner.py b/core/co4e_runner.py
index 5308700..96acad9 100644
--- a/core/co4e_runner.py
+++ b/core/co4e_runner.py
@@ -29,6 +29,9 @@ CancelFn = Callable[[], bool]
 
 
 def _predecessors(nodes: List[Node], edges: List[Edge]) -> Dict[str, List[str]]:
+    """Bảng ``{node: các node đứng trước}`` — dùng để gom đầu ra của bước trước làm
+    ngữ cảnh cho bước sau.
+    """
     ids = {n.id for n in nodes}
     preds: Dict[str, List[str]] = {n.id: [] for n in nodes}
     for e in edges:
@@ -38,6 +41,7 @@ def _predecessors(nodes: List[Node], edges: List[Edge]) -> Dict[str, List[str]]:
 
 
 def _label_of(nodes: List[Node], node_id: str) -> str:
+    """Nhãn hiển thị của một node; trả về chính id nếu không tìm thấy."""
     for n in nodes:
         if n.id == node_id:
             return n.data.label
@@ -62,6 +66,10 @@ def _attachments_text(node, out_dir=None) -> str:
     parts, budget = [], _MAX_ATTACH_CHARS
 
     def _read_into(path, label, indent=""):
+        """Đọc một tệp đính kèm vào phần ngữ cảnh, trừ dần vào hạn mức ký tự chung.
+
+        Có hạn mức vì vài tệp lớn là đủ đẩy cả lượt chạy vượt cửa sổ ngữ cảnh.
+        """
         nonlocal budget
         name = _P(path).name
         if is_image(path):
@@ -97,6 +105,7 @@ def _attachments_text(node, out_dir=None) -> str:
 
 
 def _last_assistant_text(messages: List[dict]) -> str:
+    """Nội dung trả lời cuối cùng của assistant; '' nếu không có."""
     for m in reversed(messages):
         if m.get("role") == "assistant" and m.get("content"):
             return str(m["content"])
@@ -245,6 +254,7 @@ def run_workflow(ctx, nodes: List[Node], edges: List[Edge], out_dir: Path,
 
     # Group compiled stages by wave, preserving per-node context threading.
     def extra_context_for(node_id: str) -> Dict[str, str]:
+        """Ngữ cảnh thêm cho một bước: tệp đính kèm của nó cộng đầu ra của các bước đứng trước."""
         parts = []
         att = _attachments_text(by_id.get(node_id), out_dir)
         if att:
diff --git a/core/code_agent.py b/core/code_agent.py
index 9cb47c6..088df89 100644
--- a/core/code_agent.py
+++ b/core/code_agent.py
@@ -31,6 +31,11 @@ _TOOL_LINE = re.compile(r"@@TOOL\s+(\w+)\s+(\{.*\})", re.DOTALL)
 
 def code_system_prompt(workdir: Path, has_memory: bool = False, plan: bool = False,
                        has_plan_tool: bool = False, has_ms365: bool = False) -> str:
+    """Prompt hệ thống cho Code agent, ghép theo năng lực thật của lượt chạy.
+
+    Chỉ liệt kê những tool đang BẬT, và thêm ghi chú chế độ lập kế hoạch khi cần —
+    nói với model về một tool nó không có sẽ khiến nó gọi rồi báo lỗi.
+    """
     names = ", ".join(t.name for t in TOOL_SPECS)
     plan_note = ("PLAN MODE: only analyze and propose a detailed plan; do NOT write files or run "
                  "commands. When the user asks to gencode/implement, the app switches to ACT.\n"
diff --git a/core/codebase_memory.py b/core/codebase_memory.py
index 1684908..7c2acd3 100644
--- a/core/codebase_memory.py
+++ b/core/codebase_memory.py
@@ -26,6 +26,7 @@ _INDEX_TIMEOUT = 900
 
 
 class CodebaseMemoryError(RuntimeError):
+    """Lỗi khi gọi công cụ codebase-memory-mcp bên ngoài."""
     pass
 
 
@@ -75,14 +76,24 @@ def _extract_json(text: str):
 
 
 class CodebaseMemory:
+    """Vỏ bọc quanh CLI ``codebase-memory-mcp``: đánh chỉ mục và tra cứu mã nguồn.
+
+    Đây là phần mềm ngoài, có thể không được cài — luôn kiểm :meth:`available`
+    trước khi dùng.
+    """
     def __init__(self, binary_path: str = ""):
+        """Tìm file thực thi codebase-memory; không có thì ``available`` là False và
+        mọi lượt gọi về sau tự bỏ qua.
+        """
         self.binary = resolve_binary(binary_path)
 
     @property
     def available(self) -> bool:
+        """Đã tìm thấy CLI trên máy chưa."""
         return self.binary is not None
 
     def _run(self, tool: str, args: Dict[str, Any], timeout: int) -> Dict[str, Any]:
+        """Gọi một tool của CLI và trả kết quả JSON; chưa cài thì báo lỗi kèm hướng dẫn."""
         if not self.binary:
             raise CodebaseMemoryError(
                 "codebase-memory-mcp is not installed. See the instructions in Settings."
@@ -107,12 +118,15 @@ class CodebaseMemory:
 
     # ---- high level ops ---------------------------------------------
     def index_repository(self, repo_path: str) -> Dict[str, Any]:
+        """Đánh chỉ mục một repository (chạy lâu — dùng hạn giờ dài hơn)."""
         return self._run("index_repository", {"repo_path": str(repo_path)}, _INDEX_TIMEOUT)
 
     def list_projects(self) -> Dict[str, Any]:
+        """Danh sách project đã được đánh chỉ mục."""
         return self._run("list_projects", {}, _QUERY_TIMEOUT)
 
     def call(self, tool: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Gọi một tool bất kỳ, tự chọn hạn giờ theo loại việc."""
         timeout = _INDEX_TIMEOUT if tool == "index_repository" else _QUERY_TIMEOUT
         return self._run(tool, args, timeout)
 
@@ -187,6 +201,9 @@ def make_executor(mem: CodebaseMemory):
     """Return an executor(name, args) -> {ok, output} for cmem_* tools."""
 
     def execute(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Bộ thực thi tool codebase-memory cho agent; tên tool lạ thì trả về lỗi thay
+        vì ném ngoại lệ.
+        """
         cli_tool = _CLI_NAME.get(name)
         if not cli_tool:
             return {"ok": False, "output": f"Unsupported codebase-memory tool: {name}"}
diff --git a/core/codebase_memory_ui.py b/core/codebase_memory_ui.py
index 446f350..dc4024f 100644
--- a/core/codebase_memory_ui.py
+++ b/core/codebase_memory_ui.py
@@ -33,6 +33,9 @@ class CmemUiError(RuntimeError):
     asset) — a different remedy than a generic startup/timeout failure."""
 
     def __init__(self, message: str, no_ui_build: bool = False):
+        """``no_ui_build`` đánh dấu trường hợp riêng: chạy được nhưng bản cài không kèm
+        phần giao diện — thông báo cho người dùng phải khác hẳn lỗi chạy thường.
+        """
         super().__init__(message)
         self.no_ui_build = no_ui_build
 
@@ -41,16 +44,21 @@ class CodebaseMemoryUiServer:
     """One ``codebase-memory-mcp --ui`` process, started on demand."""
 
     def __init__(self, binary_path: str = "", port: int = DEFAULT_PORT):
+        """Chuẩn bị chỗ chạy máy chủ giao diện; chưa khởi động tiến trình nào."""
         self.binary = resolve_binary(binary_path)
         self.port = port
         self._proc: Optional[subprocess.Popen] = None
 
     @property
     def url(self) -> str:
+        """Địa chỉ để mở giao diện. Chỉ nghe trên 127.0.0.1 — đây là công cụ cục bộ,
+        không mở ra mạng.
+        """
         return f"http://127.0.0.1:{self.port}/"
 
     @property
     def running(self) -> bool:
+        """Tiến trình máy chủ còn sống không."""
         return self._proc is not None and self._proc.poll() is None
 
     def start(self, repo_path: str = "") -> str:
@@ -75,6 +83,9 @@ class CodebaseMemoryUiServer:
         no_ui_event = threading.Event()
 
         def _reader() -> None:
+            """Chạy nền: đọc đầu ra của tiến trình, giữ lại để báo lỗi và bật cờ khi thấy
+            dấu hiệu bản cài không có phần giao diện.
+            """
             try:
                 stream = self._proc.stdout
                 if stream is None:
@@ -111,6 +122,11 @@ class CodebaseMemoryUiServer:
         raise CmemUiError(f"Hết thời gian chờ UI trên cổng {self.port}.")
 
     def stop(self) -> None:
+        """Dừng máy chủ. Xin dừng tử tế trước, quá 3 giây thì buộc tắt.
+
+        Mọi lỗi đều bị nuốt có chủ ý: đây là dọn dẹp lúc thoát, ném lỗi ở đây chỉ
+        làm kẹt đường thoát của cả ứng dụng.
+        """
         proc, self._proc = self._proc, None
         if proc is not None and proc.poll() is None:
             try:
diff --git a/core/context_budget.py b/core/context_budget.py
index 6f4301c..b26b737 100644
--- a/core/context_budget.py
+++ b/core/context_budget.py
@@ -33,6 +33,9 @@ _MODEL_LIMITS = {
 
 
 def model_context_limit(model: str) -> int:
+    """Cửa sổ ngữ cảnh (token) của một model, dò theo tiền tố tên dài nhất khớp
+    trong bảng; không khớp gì thì lấy ``DEFAULT_LIMIT``.
+    """
     m = (model or "").lower()
     best = 0
     limit = DEFAULT_LIMIT
@@ -43,6 +46,7 @@ def model_context_limit(model: str) -> int:
 
 
 def _ctx_conf(config) -> Dict[str, Any]:
+    """Nhóm cấu hình ``context``; không có config thì trả dict rỗng."""
     if config is None:
         return {}
     try:
@@ -59,11 +63,13 @@ def context_limit(config, model: str = "") -> int:
 
 
 def auto_compact_enabled(config) -> bool:
+    """Có tự nén lịch sử khi gần đầy ngữ cảnh không (mặc định bật)."""
     conf = _ctx_conf(config)
     return bool(conf.get("auto_compact", True))
 
 
 def threshold(config) -> float:
+    """Ngưỡng nén, tính theo tỉ lệ cửa sổ ngữ cảnh đã dùng (mặc định 0,8)."""
     conf = _ctx_conf(config)
     try:
         t = float(conf.get("compact_threshold", DEFAULT_THRESHOLD))
@@ -73,6 +79,9 @@ def threshold(config) -> float:
 
 
 def _msg_text(m: Dict[str, Any]) -> str:
+    """Rút phần văn bản của một tin nhắn, kể cả khi nội dung là danh sách block
+    (tin nhắn có ảnh).
+    """
     c = m.get("content", "")
     if isinstance(c, str):
         return c
@@ -81,11 +90,17 @@ def _msg_text(m: Dict[str, Any]) -> str:
 
 
 def estimate_messages_tokens(messages: List[Dict[str, Any]]) -> int:
+    """Ước lượng tổng token của cả danh sách tin nhắn."""
     return sum(estimate_tokens(_msg_text(m)) for m in messages)
 
 
 def should_compact(messages: List[Dict[str, Any]], limit: int,
                    thresh: float = DEFAULT_THRESHOLD) -> bool:
+    """Đã đến lúc nén lịch sử chưa.
+
+    Không nén khi hội thoại còn quá ngắn: nén một cuộc mới vài lượt thì mất nội
+    dung mà chẳng tiết kiệm được bao nhiêu.
+    """
     if limit <= 0 or len(messages) <= _KEEP_RECENT + 2:
         return False
     return estimate_messages_tokens(messages) > limit * thresh
@@ -99,6 +114,7 @@ _SUMMARY_PROMPT = (
 
 
 def _summarize(provider, middle: List[Dict[str, Any]], cancel=None) -> str:
+    """Nhờ model tóm tắt phần giữa của hội thoại thành một đoạn ngắn."""
     convo = "\n\n".join(f"[{m.get('role', '?')}] {_msg_text(m)}" for m in middle)
     try:
         a = provider.chat([{"role": "system", "content": _SUMMARY_PROMPT},
diff --git a/core/cron.py b/core/cron.py
index 9d59cc1..4084011 100644
--- a/core/cron.py
+++ b/core/cron.py
@@ -15,10 +15,14 @@ _SEARCH_DAYS = 366 * 2   # give up after two years (an expression that never fir
 
 
 class CronError(ValueError):
+    """Biểu thức cron sai cú pháp."""
     pass
 
 
 def _parse_field(spec: str, lo: int, hi: int) -> Set[int]:
+    """Đọc một trường cron thành tập giá trị: hỗ trợ ``*``, danh sách ``a,b``,
+    khoảng ``a-b`` và bước ``*/n``.
+    """
     values: Set[int] = set()
     for part in spec.split(","):
         part = part.strip()
@@ -55,7 +59,13 @@ def _parse_field(spec: str, lo: int, hi: int) -> Set[int]:
 
 
 class Cron:
+    """Biểu thức cron 5 trường (phút, giờ, ngày, tháng, thứ)."""
     def __init__(self, expression: str):
+        """Phân tích một biểu thức cron 5 trường.
+
+        Sai số trường là ném ``CronError`` ngay tại đây chứ không đợi tới lúc chạy:
+        lịch sai giờ khó phát hiện hơn nhiều so với một lỗi lúc nhập.
+        """
         fields = (expression or "").split()
         if len(fields) != 5:
             raise CronError("Cron expression needs exactly 5 fields: "
@@ -69,6 +79,11 @@ class Cron:
         self._dow_star = fields[4].strip() == "*"
 
     def _day_matches(self, dt: datetime) -> bool:
+        """Ngày này có khớp biểu thức không.
+
+        Theo chuẩn cron: khi cả trường NGÀY và trường THỨ đều được đặt cụ thể thì
+        khớp một trong hai là đủ (OR), chứ không phải cả hai (AND).
+        """
         if dt.month not in self.months:
             return False
         cron_dow = (dt.weekday() + 1) % 7    # Python Mon=0 → cron Sun=0
diff --git a/core/custom_agents.py b/core/custom_agents.py
index 34cfc6f..c07a2f2 100644
--- a/core/custom_agents.py
+++ b/core/custom_agents.py
@@ -21,6 +21,14 @@ AGENTS_DIR = CONFIG_DIR / "agents"
 
 @dataclass
 class CustomAgent:
+    """Một agent do người dùng tự tạo: tên, mô tả, prompt mặc định và tuỳ chọn
+    provider/model riêng.
+
+    Bỏ trống ``provider``/``model`` nghĩa là dùng theo bước gọi nó hoặc theo cấu
+    hình chung — nhờ vậy một agent viết một lần chạy được với mọi provider.
+
+    Đã được ``core/co4e.py`` thay thế; giữ lại làm bản đối chiếu.
+    """
     name: str
     description: str = ""
     prompt: str = ""     # default task; a Flow sub-agent can still override it
@@ -29,16 +37,25 @@ class CustomAgent:
 
     @property
     def slug(self) -> str:
+        """Tên rút gọn an toàn để đặt tên file, ví dụ "Trợ lý Code" -> "tro-ly-code".
+        Tên không còn ký tự hợp lệ nào thì rơi về "agent".
+        """
         keep = "-_"
         s = "".join(c if (c.isalnum() or c in keep) else "-" for c in self.name.strip().lower())
         return "-".join(filter(None, s.split("-"))) or "agent"
 
 
 def agents_dir() -> Path:
+    """Thư mục chứa file agent tự tạo."""
     return AGENTS_DIR
 
 
 def list_agents(directory: Path = AGENTS_DIR) -> List[CustomAgent]:
+    """Đọc mọi agent trong thư mục, sắp theo tên file.
+
+    File hỏng bị bỏ riêng lẻ chứ không làm hỏng cả danh sách — một file sai
+    không được phép làm mất hết agent còn lại.
+    """
     if not directory.exists():
         return []
     agents: List[CustomAgent] = []
@@ -58,6 +75,11 @@ def list_agents(directory: Path = AGENTS_DIR) -> List[CustomAgent]:
 
 
 def save_agent(agent: CustomAgent, directory: Path = AGENTS_DIR, old_name: str = "") -> Path:
+    """Ghi một agent xuống đĩa.
+
+    Truyền ``old_name`` khi đổi tên: file cũ bị xoá trước, nếu không sẽ có hai
+    file cùng nội dung với hai tên khác nhau.
+    """
     directory.mkdir(parents=True, exist_ok=True)
     if old_name and old_name != agent.name:
         delete_agent(old_name, directory)
@@ -67,6 +89,9 @@ def save_agent(agent: CustomAgent, directory: Path = AGENTS_DIR, old_name: str =
 
 
 def delete_agent(name: str, directory: Path = AGENTS_DIR) -> None:
+    """Xoá file của một agent theo tên. Không có file thì thôi; lỗi xoá bị nuốt,
+    không chặn giao diện.
+    """
     path = directory / f"{CustomAgent(name=name).slug}.json"
     if path.exists():
         try:
diff --git a/core/custom_icons.py b/core/custom_icons.py
index 6ccc69f..84dd629 100644
--- a/core/custom_icons.py
+++ b/core/custom_icons.py
@@ -18,15 +18,18 @@ _MAX_BYTES = 200_000
 
 
 def icons_dir() -> Path:
+    """Thư mục chứa icon do người dùng thêm."""
     return ICONS_DIR
 
 
 def slugify(name: str) -> str:
+    """Định danh an toàn cho tên file icon; rỗng thì trả về 'icon'."""
     s = "".join(c if (c.isalnum() or c in "-_") else "-" for c in (name or "").strip().lower())
     return "-".join(filter(None, s.split("-"))) or "icon"
 
 
 def list_custom(directory: Optional[Path] = None) -> List[str]:
+    """Tên các icon tự thêm; thư mục chưa có thì trả list rỗng."""
     directory = directory or ICONS_DIR
     if not directory.exists():
         return []
@@ -69,6 +72,7 @@ def add_from_file(path, name: str = "", directory: Optional[Path] = None) -> str
 
 
 def delete_custom(name: str, directory: Optional[Path] = None) -> None:
+    """Xoá một icon tự thêm; không có thì bỏ qua."""
     directory = directory or ICONS_DIR
     path = directory / f"{slugify(name)}.svg"
     if path.exists():
diff --git a/core/d3_graph.py b/core/d3_graph.py
index f7340f3..20b30c2 100644
--- a/core/d3_graph.py
+++ b/core/d3_graph.py
@@ -18,6 +18,7 @@ _CDN_D3 = '<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.5/d3.min.j
 
 
 def build_html(graph) -> str:
+    """Dựng trang HTML D3 cho đồ thị: nhét dữ liệu node/cạnh vào bản mẫu."""
     html = TEMPLATE.read_text(encoding="utf-8")
 
     # Inline a bundled d3 (offline) if present; else keep the CDN reference.
diff --git a/core/deps.py b/core/deps.py
index 361dcc2..8ec5d10 100644
--- a/core/deps.py
+++ b/core/deps.py
@@ -29,6 +29,7 @@ _ACTIVE_PIDS: set[int] = set()
 
 
 def active_pids() -> List[int]:
+    """Pid của các tiến trình con đang chạy — dùng để dọn sạch khi thoát app."""
     with _active_pids_lock:
         return sorted(_ACTIVE_PIDS)
 
@@ -142,6 +143,11 @@ def _run_cancellable_body(
     proc: "subprocess.Popen", cancel: CancelFn, timeout: Optional[float],
     on_output: Optional[Callable[[str], None]], limits: Optional[Dict[str, float]],
 ) -> Tuple[Optional[int], str, bool, bool, bool]:
+    """Chạy một tiến trình con có thể huỷ giữa chừng, có hạn giờ và có giới hạn tài nguyên.
+
+    Trên Windows gắn tiến trình vào một Job Object để khi giết là giết cả cây
+    tiến trình con — giết mỗi tiến trình cha sẽ để lại đám con mồ côi.
+    """
     job_handle = None
     if sys.platform == "win32":
         from .win_job import assign_process, create_job_object
@@ -158,6 +164,11 @@ def _run_cancellable_body(
     collected: Dict[str, list] = {"out": [], "err": []}
 
     def _read_stream(stream, key: str) -> None:
+        """Đọc một luồng đầu ra theo từng dòng ở luồng riêng.
+
+        Phải đọc song song stdout và stderr: đọc lần lượt sẽ kẹt khi tiến trình con
+        làm đầy bộ đệm của luồng còn lại.
+        """
         try:
             for line in iter(stream.readline, ""):
                 collected[key].append(line)
@@ -239,6 +250,7 @@ def network_blocked_env(base_env: Optional[Dict[str, str]] = None) -> Dict[str,
 
 def _can_pip() -> bool:
     # A PyInstaller/py2exe build has no usable pip; don't attempt installs there.
+    """Bản đóng gói (PyInstaller) không có pip dùng được — đừng thử cài gì ở đó."""
     return not getattr(sys, "frozen", False)
 
 
@@ -267,6 +279,7 @@ def ensure_module(module: str, package: str | None = None):
 
 
 def venv_python_path(venv_dir: Path) -> Path:
+    """Đường dẫn tới ``python`` trong một virtualenv, khác nhau giữa Windows và POSIX."""
     return venv_dir / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
 
 
diff --git a/core/doc_extract.py b/core/doc_extract.py
index 516bc26..04ffd74 100644
--- a/core/doc_extract.py
+++ b/core/doc_extract.py
@@ -23,6 +23,7 @@ IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".tiff", ".tif",
 
 
 def is_image(path) -> bool:
+    """Đuôi tệp này có phải ảnh không."""
     return Path(path).suffix.lower() in IMAGE_EXTS
 
 
@@ -164,6 +165,10 @@ def extract_text(path, progress=None) -> tuple[str | None, str]:
 # Office Open XML (docx / xlsx / pptx)
 # --------------------------------------------------------------------------
 def _docx(p: Path) -> str:
+    """Trích văn bản từ .docx bằng cách đọc thẳng XML trong gói zip.
+
+    Không cần thư viện ngoài — .docx vốn là một file zip chứa XML.
+    """
     with zipfile.ZipFile(p) as z:
         xml = z.read("word/document.xml").decode("utf-8", "replace")
     out: list[str] = []
@@ -179,6 +184,7 @@ def _docx(p: Path) -> str:
 
 
 def _pptx(p: Path) -> str:
+    """Trích văn bản từ .pptx, đi theo đúng thứ tự slide."""
     out: list[str] = []
     with zipfile.ZipFile(p) as z:
         slides = [n for n in z.namelist() if re.match(r"ppt/slides/slide\d+\.xml$", n)]
@@ -192,6 +198,11 @@ def _pptx(p: Path) -> str:
 
 
 def _xlsx(p: Path) -> str:
+    """Trích văn bản từ .xlsx, có phân giải bảng chuỗi dùng chung.
+
+    Excel lưu chuỗi trong một bảng riêng và ô chỉ giữ chỉ số — đọc thẳng ô sẽ ra
+    toàn số.
+    """
     with zipfile.ZipFile(p) as z:
         names = z.namelist()
         shared: list[str] = []
@@ -235,6 +246,7 @@ def _xlsx(p: Path) -> str:
 # OpenDocument (odt / ods / odp)
 # --------------------------------------------------------------------------
 def _odf(p: Path) -> str:
+    """Trích văn bản từ tài liệu OpenDocument (.odt/.ods/.odp)."""
     with zipfile.ZipFile(p) as z:
         xml = z.read("content.xml").decode("utf-8", "replace")
     xml = re.sub(r"<text:line-break\s*/>", "\n", xml)
@@ -249,6 +261,10 @@ def _odf(p: Path) -> str:
 # PDF + LibreOffice fallback
 # --------------------------------------------------------------------------
 def _pdf(p: Path, progress=None) -> tuple[str | None, str]:
+    """Trích văn bản từ PDF bằng ``pypdf``, tự cài nếu thiếu.
+
+    Trả về (văn bản, ghi chú); văn bản là ``None`` khi không trích được.
+    """
     from .deps import ensure_module
 
     # Auto-install pypdf when missing (no manual install needed); fall back to
@@ -369,6 +385,11 @@ def _office_com_to_pdf(src: Path, pdf: Path) -> str | None:
 
 
 def _soffice_to_text(p: Path) -> tuple[str | None, str]:
+    """Cách dự phòng cuối: nhờ LibreOffice chuyển tài liệu sang văn bản.
+
+    Dùng cho định dạng không có bộ đọc riêng; không cài LibreOffice thì trả về
+    lý do để chỗ gọi hiện ra.
+    """
     soffice = find_soffice()
     if not soffice:
         return None, "no extractor available (install LibreOffice)"
diff --git a/core/doc_style_extract.py b/core/doc_style_extract.py
index 5b51dad..9734009 100644
--- a/core/doc_style_extract.py
+++ b/core/doc_style_extract.py
@@ -21,6 +21,10 @@ _RUN_PREVIEW_CHARS = 40
 
 
 def _run_style(font) -> str:
+    """Mô tả định dạng một đoạn chữ (đậm, nghiêng, cỡ, màu) thành chuỗi ngắn.
+
+    Dùng để AI sửa tài liệu mà vẫn giữ được định dạng gốc.
+    """
     bits: list[str] = []
     try:
         if font.name:
diff --git a/core/ext_connectors.py b/core/ext_connectors.py
index a3d980f..ea2cd27 100644
--- a/core/ext_connectors.py
+++ b/core/ext_connectors.py
@@ -79,6 +79,7 @@ def new_connector(category: str, preset_id: str = "", name: str = "") -> Dict[st
 
 
 def _redact(entry: Dict[str, Any]) -> Dict[str, Any]:
+    """Bản sao đã che các trường nhạy cảm (khoá, token) — dùng khi ghi log/kiểm toán."""
     out = dict(entry)
     for k in _SENSITIVE_KEYS:
         if out.get(k):
@@ -92,6 +93,11 @@ class RestApiConnector:
     vendor documents without this app knowing that vendor's API shape."""
 
     def __init__(self, entry: Dict[str, Any]):
+        """Đọc một khai báo connector REST.
+
+        ``base_url`` luôn được chuẩn hoá thành có đúng một dấu ``/`` ở cuối, để ghép
+        đường dẫn về sau không sinh ra ``//`` hay dính liền.
+        """
         self.id = entry.get("id") or entry.get("name", "")
         self.display_name = entry.get("name") or self.id
         self.base_url = (entry.get("base_url") or "").rstrip("/") + "/"
@@ -100,6 +106,9 @@ class RestApiConnector:
         self.auth_scheme = entry.get("auth_scheme") or "Bearer"
 
     def tool_spec(self) -> ToolSpec:
+        """Khai báo tool để đưa cho model; tên tool có tiền tố là id connector nên hai
+        connector không đụng tên nhau.
+        """
         return ToolSpec(
             name=f"{self.id}{_SEP}http_request",
             description=(
@@ -122,6 +131,7 @@ class RestApiConnector:
         )
 
     def call(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Gọi API theo tham số model đưa ra, đi qua lớp TLS có ghim chứng chỉ nội bộ."""
         from .tls_trust import request_any_method as tls_request
 
         method = str(args.get("method", "GET")).upper()
@@ -153,6 +163,7 @@ class RestApiConnector:
         return {"ok": ok, "output": f"HTTP {resp.status_code}\n{text}"}
 
     def test_connection(self) -> Tuple[bool, str]:
+        """Thử kết nối tới endpoint; trả về (thành công, thông điệp)."""
         from .tls_trust import request as tls_request
 
         if not self.base_url.strip("/"):
diff --git a/core/flows.py b/core/flows.py
index b7adf8b..d60f921 100644
--- a/core/flows.py
+++ b/core/flows.py
@@ -30,6 +30,7 @@ class SubAgent:
 
 @dataclass
 class FlowStep:
+    """Một bước trong luồng cũ: prompt, skill áp dụng, và danh sách agent chạy song song."""
     name: str
     prompt: str = ""
     skill: str = ""    # skill name to apply on this step ("" = none)
@@ -44,11 +45,13 @@ class FlowStep:
 
     @property
     def is_parallel(self) -> bool:
+        """Bước này có chạy nhiều agent song song hay không."""
         return bool(self.parallel_agents)
 
 
 @dataclass
 class Flow:
+    """Một luồng cũ: tên, mô tả, và danh sách bước chạy tuần tự."""
     name: str
     description: str = ""
     steps: List[FlowStep] = field(default_factory=list)
@@ -77,6 +80,11 @@ class FlowRunStatus:
     substeps: List[dict] = field(default_factory=list)
 
     def state_of(self, i: int) -> str:
+        """Trạng thái hiển thị của bước thứ ``i``: xong, đang chạy, lỗi hay còn chờ.
+
+        Chỉ bước ngay TRƯỚC con trỏ mới được đánh dấu lỗi — các bước xong trước đó
+        vẫn là xong.
+        """
         if i < self.done:
             if self.last_error and i == self.done - 1:
                 return STEP_ERROR
@@ -97,11 +105,13 @@ class FlowRunStatus:
 
 
 def _slug(name: str) -> str:
+    """Định danh an toàn cho tên file, suy từ tên luồng."""
     s = "".join(c if (c.isalnum() or c in "-_") else "-" for c in name.strip().lower())
     return "-".join(filter(None, s.split("-"))) or "flow"
 
 
 def flows_dir() -> Path:
+    """Thư mục chứa file luồng cũ."""
     return FLOWS_DIR
 
 
@@ -126,11 +136,13 @@ def default_req_to_demo() -> Flow:
 
 
 def to_dict(flow: Flow) -> dict:
+    """Chuyển một luồng thành dict để ghi JSON."""
     return {"name": flow.name, "description": flow.description,
             "steps": [asdict(s) for s in flow.steps]}
 
 
 def from_dict(data: dict) -> Flow:
+    """Dựng :class:`Flow` từ dict đọc trên đĩa, lọc bỏ khoá lạ."""
     steps = []
     for raw in data.get("steps", []):
         raw = dict(raw)
@@ -142,6 +154,7 @@ def from_dict(data: dict) -> Flow:
 
 
 def list_flows(directory: Path = FLOWS_DIR) -> List[Flow]:
+    """Liệt kê mọi luồng đã lưu; thư mục chưa có thì trả list rỗng."""
     if not directory.exists():
         return []
     flows: List[Flow] = []
@@ -154,6 +167,11 @@ def list_flows(directory: Path = FLOWS_DIR) -> List[Flow]:
 
 
 def save_flow(flow: Flow, directory: Path = FLOWS_DIR, old_name: str = "") -> Path:
+    """Ghi một luồng xuống đĩa.
+
+    Đổi tên thì XOÁ file cũ trước — tên file suy từ tên luồng, không xoá sẽ để
+    lại một bản sao dưới tên cũ.
+    """
     directory.mkdir(parents=True, exist_ok=True)
     if old_name and old_name != flow.name:
         delete_flow(old_name, directory)
@@ -163,6 +181,7 @@ def save_flow(flow: Flow, directory: Path = FLOWS_DIR, old_name: str = "") -> Pa
 
 
 def delete_flow(name: str, directory: Path = FLOWS_DIR) -> None:
+    """Xoá file luồng theo tên; không có thì bỏ qua."""
     path = directory / f"{_slug(name)}.json"
     if path.exists():
         try:
@@ -269,19 +288,23 @@ class FlowRunner:
 
     @property
     def step_index(self) -> int:
+        """Chỉ số bước đang chạy."""
         return self._index
 
     def current_step(self) -> Optional[FlowStep]:
+        """Bước đang chạy; ``None`` khi đã hết bước."""
         if 0 <= self._index < len(self.flow.steps):
             return self.flow.steps[self._index]
         return None
 
     def start(self) -> FlowAction:
+        """Bắt đầu chạy luồng và trả về hành động đầu tiên cần thực hiện."""
         if self.current_step() is None:
             return FlowAction(kind="done")
         return self._step_action()
 
     def _step_action(self) -> FlowAction:
+        """Hành động cho bước hiện tại: chạy một agent, hay chia ra nhiều agent song song."""
         step = self.current_step()
         self._phase = "step"
         if step.is_parallel:
@@ -326,6 +349,7 @@ class FlowRunner:
         return self._advance(compact=compact)
 
     def _advance(self, compact: bool) -> FlowAction:
+        """Sang bước kế tiếp; hết bước thì báo luồng đã xong."""
         self._index += 1
         if self.current_step() is None:
             return FlowAction(kind="done", compact=compact)
diff --git a/core/graph_server.py b/core/graph_server.py
index fba529c..7619475 100644
--- a/core/graph_server.py
+++ b/core/graph_server.py
@@ -28,6 +28,12 @@ class GraphServer:
     """Lazy singleton-per-instance localhost server for the D3 graph page."""
 
     def __init__(self) -> None:
+        """Chuẩn bị máy chủ; chưa mở cổng nào.
+
+        Một token ngẫu nhiên được sinh ngay lúc này và mọi yêu cầu đều phải mang
+        nó: máy chủ nghe trên localhost, nhưng mọi tiến trình khác trên cùng máy đều
+        gọi được localhost.
+        """
         self._html = _PLACEHOLDER
         self._token = secrets.token_urlsafe(16)
         self._lock = threading.Lock()
@@ -37,6 +43,7 @@ class GraphServer:
 
     # ---- content / callbacks ----------------------------------------
     def set_html(self, html: str) -> None:
+        """Đặt nội dung HTML sẽ phục vụ; có khoá vì luồng nền ghi còn luồng HTTP đọc."""
         with self._lock:
             self._html = html
 
@@ -47,10 +54,12 @@ class GraphServer:
     # ---- lifecycle ----------------------------------------------------
     @property
     def running(self) -> bool:
+        """Máy chủ có đang chạy không."""
         return self._httpd is not None
 
     @property
     def url(self) -> str:
+        """URL đầy đủ kèm token; '' nếu chưa chạy."""
         if self._httpd is None:
             return ""
         port = self._httpd.server_address[1]
@@ -63,14 +72,22 @@ class GraphServer:
         server = self
 
         class Handler(BaseHTTPRequestHandler):
+            """Handler HTTP: chỉ phục vụ đúng trang đồ thị, và chỉ khi token khớp."""
             def log_message(self, *_a) -> None:  # keep the GUI console silent
+                """Tắt log của thư viện chuẩn — nếu không, console GUI bị ngập request."""
                 pass
 
             def _authorized(self, query: dict) -> bool:
+                """Kiểm token trong query, so sánh theo kiểu chống dò thời gian.
+
+                Máy chủ này nghe trên localhost nhưng vẫn cần token: mọi tiến trình khác
+                trên cùng máy đều gọi được nó.
+                """
                 supplied = (query.get("t") or [""])[0]
                 return secrets.compare_digest(supplied, server._token)
 
             def do_GET(self) -> None:  # noqa: N802 - stdlib naming
+                """Trả trang đồ thị khi token đúng; sai token thì trả 403."""
                 parsed = urlparse(self.path)
                 query = parse_qs(parsed.query)
                 if not self._authorized(query):
@@ -108,6 +125,7 @@ class GraphServer:
         return self.url
 
     def stop(self) -> None:
+        """Dừng máy chủ và giải phóng cổng."""
         httpd, self._httpd = self._httpd, None
         if httpd is not None:
             httpd.shutdown()
diff --git a/core/groups.py b/core/groups.py
index f9600d4..c0492cf 100644
--- a/core/groups.py
+++ b/core/groups.py
@@ -15,6 +15,7 @@ from typing import List, Optional
 
 @dataclass
 class Group:
+    """Một nhóm người dùng: id, tên, và tài khoản quản trị nhóm."""
     group_id: str
     name: str
     subadmin_username: str = ""
@@ -23,16 +24,19 @@ class Group:
 
 
 def groups_dir(shared_dir: str) -> Path:
+    """Thư mục chứa nhóm, nằm trong thư mục chia sẻ của đội."""
     return Path(shared_dir).expanduser() / "groups"
 
 
 def new_group(name: str, subadmin_username: str = "") -> Group:
+    """Tạo một nhóm mới với id ngẫu nhiên và mốc thời gian tạo."""
     return Group(group_id=uuid.uuid4().hex, name=name.strip() or "Group",
                 subadmin_username=subadmin_username,
                 created=datetime.now().isoformat(timespec="seconds"))
 
 
 def save_group(group: Group, directory: Path) -> Path:
+    """Ghi một nhóm ra ``<group_id>.json``."""
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{group.group_id}.json"
     path.write_text(json.dumps(asdict(group), ensure_ascii=False, indent=2), encoding="utf-8")
@@ -40,6 +44,7 @@ def save_group(group: Group, directory: Path) -> Path:
 
 
 def load_group(group_id: str, directory: Path) -> Optional[Group]:
+    """Đọc một nhóm theo id; id được làm sạch trước để không thoát khỏi thư mục."""
     safe_id = re.sub(r"[^\w\-]", "", group_id or "")
     path = directory / f"{safe_id}.json"
     if not path.exists():
@@ -53,6 +58,7 @@ def load_group(group_id: str, directory: Path) -> Optional[Group]:
 
 
 def list_groups(directory: Path) -> List[Group]:
+    """Liệt kê mọi nhóm trong thư mục; thư mục chưa có thì trả list rỗng."""
     if not directory.exists():
         return []
     out: List[Group] = []
@@ -65,6 +71,7 @@ def list_groups(directory: Path) -> List[Group]:
 
 
 def delete_group(group_id: str, directory: Path) -> bool:
+    """Xoá file nhóm; id rỗng hoặc không có file thì trả ``False``."""
     safe_id = re.sub(r"[^\w\-]", "", group_id or "")
     if not safe_id:
         return False
diff --git a/core/history.py b/core/history.py
index 4dfb4e9..7575baa 100644
--- a/core/history.py
+++ b/core/history.py
@@ -18,10 +18,15 @@ from typing import Any, Dict, List
 
 
 def new_session_id() -> str:
+    """Id phiên mới theo mốc thời gian, chính xác tới mili giây."""
     return datetime.now().strftime("%Y%m%d-%H%M%S-%f")[:-3]
 
 
 def derive_title(messages: List[Dict[str, Any]]) -> str:
+    """Suy tiêu đề hội thoại từ tin nhắn đầu tiên của người dùng.
+
+    Dùng khi người dùng chưa tự đặt tên — cắt gọn cho vừa một dòng danh sách.
+    """
     for m in messages:
         if m.get("role") == "user" and m.get("content"):
             text = " ".join(m["content"].split())
@@ -40,6 +45,12 @@ def save_conversation(
     outputs: List[str] | None = None,
     project_id: str = "",
 ) -> Path:
+    """Ghi một hội thoại xuống ``<kind>__<session_id>.json``.
+
+    Ghi nguyên tử (R06-T02). Cờ ghim và project_id của lần lưu trước được GIỮ
+    LẠI: hàm này bị gọi tự động sau mỗi lượt chat, ghi đè chúng sẽ âm thầm bỏ
+    ghim và đẩy hội thoại ra khỏi project của nó.
+    """
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{kind}__{session_id}.json"
     pinned = False  # preserve pin flag + project across autosaves
@@ -71,6 +82,7 @@ def save_conversation(
 
 
 def delete_conversation(path) -> None:
+    """Xoá file hội thoại; không có thì bỏ qua."""
     try:
         Path(path).unlink()
     except OSError:
@@ -78,6 +90,7 @@ def delete_conversation(path) -> None:
 
 
 def rename_conversation(path, new_title: str) -> None:
+    """Đổi tiêu đề một hội thoại và ghi lại (nguyên tử)."""
     from ..infrastructure.persistence.json.atomic_write import write_json
 
     data = load_conversation(path)
@@ -86,6 +99,7 @@ def rename_conversation(path, new_title: str) -> None:
 
 
 def set_pinned(path, pinned: bool) -> None:
+    """Ghim/bỏ ghim một hội thoại để nó nằm trên đầu danh sách."""
     from ..infrastructure.persistence.json.atomic_write import write_json
 
     data = load_conversation(path)
@@ -94,6 +108,9 @@ def set_pinned(path, pinned: bool) -> None:
 
 
 def load_conversation(path: Path) -> Dict[str, Any]:
+    """Đọc một hội thoại; file hỏng hoặc không đọc được thì trả về dict rỗng thay
+    vì ném lỗi — một file hỏng không được phép làm chết cả danh sách lịch sử.
+    """
     try:
         data = json.loads(Path(path).read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError):
diff --git a/core/holiday_calendar.py b/core/holiday_calendar.py
index cb0984c..624d564 100644
--- a/core/holiday_calendar.py
+++ b/core/holiday_calendar.py
@@ -44,6 +44,11 @@ def _package_calendar(country: str, year: int):
 
 
 def is_holiday(d: date, country: Optional[str]) -> bool:
+    """Ngày này có phải ngày nghỉ của một quốc gia không.
+
+    Không đặt quốc gia thì luôn trả ``False`` — không suy đoán lịch nghỉ thay
+    người dùng.
+    """
     country = (country or "").strip().upper()
     if not country:
         return False
diff --git a/core/image_gen.py b/core/image_gen.py
index 966a524..963bc33 100644
--- a/core/image_gen.py
+++ b/core/image_gen.py
@@ -28,6 +28,10 @@ _IMAGE_MODEL_MARKERS = (
 
 
 def looks_like_image_model(name: str) -> bool:
+    """Đoán một model có sinh ảnh được không, dựa trên dấu hiệu trong tên.
+
+    Đoán theo tên vì không provider nào khai báo năng lực này qua API.
+    """
     n = (name or "").lower()
     return any(m in n for m in _IMAGE_MODEL_MARKERS)
 
diff --git a/core/jira_tool.py b/core/jira_tool.py
index 88d2e93..ef5db00 100644
--- a/core/jira_tool.py
+++ b/core/jira_tool.py
@@ -20,11 +20,13 @@ _KEY_RE = re.compile(r"\b([A-Z][A-Z0-9]+-\d+)\b")
 
 
 def _conf(config: Dict[str, Any] | None) -> Dict[str, str]:
+    """Ba trường cấu hình Jira đã cắt khoảng trắng: base_url, email, api_token."""
     return {k: str((config or {}).get(k, "") or "").strip()
             for k in ("base_url", "email", "api_token")}
 
 
 def configured(config: Dict[str, Any] | None) -> bool:
+    """Đã cấu hình đủ ba trường để gọi Jira chưa."""
     c = _conf(config)
     return bool(c["base_url"] and c["email"] and c["api_token"])
 
@@ -82,6 +84,7 @@ def get_issue_by_url(config: Dict[str, Any] | None, url: str) -> str:
 
 
 def _get(config: Dict[str, Any], path: str, params: dict = None):
+    """Gọi Jira REST API bằng xác thực cơ bản, qua lớp TLS có ghim chứng chỉ nội bộ."""
     from . import tls_trust
 
     c = _conf(config)
@@ -97,6 +100,7 @@ def _get(config: Dict[str, Any], path: str, params: dict = None):
 
 
 def _fmt_issue(it: dict) -> str:
+    """Một dòng tóm tắt issue: mã, trạng thái và tiêu đề."""
     f = it.get("fields", {}) or {}
     status = (f.get("status") or {}).get("name", "?")
     assignee = (f.get("assignee") or {}).get("displayName", "unassigned")
diff --git a/core/link_fetch.py b/core/link_fetch.py
index dca30e4..455e5b4 100644
--- a/core/link_fetch.py
+++ b/core/link_fetch.py
@@ -48,6 +48,9 @@ _DOC_SUFFIXES = {".pdf", ".doc", ".docx", ".docm", ".xls", ".xlsx", ".xlsm",
 
 
 def _html_to_text(html: str) -> str:
+    """Rút văn bản đọc được từ HTML: bỏ script/style, đổi thẻ thành xuống dòng rồi
+    gộp khoảng trắng thừa.
+    """
     text = _SCRIPT_STYLE_RE.sub(" ", html)
     text = _TAG_RE.sub("\n", text)
     text = _WS_RE.sub(" ", text)
@@ -81,6 +84,10 @@ _ONEDRIVE_HOSTS = {"1drv.ms", "onedrive.live.com"}
 
 
 def _is_share_link(url: str) -> bool:
+    """Link này có phải link chia sẻ SharePoint/OneDrive không.
+
+    Loại link đó cần đi qua đường xác thực MS365 thay vì tải HTTP thường.
+    """
     host = (urlparse(url).hostname or "").lower()
     return bool(_SHAREPOINT_HOST_RE.search(host)) or host in _ONEDRIVE_HOSTS
 
diff --git a/core/mcp_client.py b/core/mcp_client.py
index 4df0701..292b478 100644
--- a/core/mcp_client.py
+++ b/core/mcp_client.py
@@ -27,6 +27,7 @@ _SEP = "__"
 
 
 class McpServerError(RuntimeError):
+    """Lỗi khi nối hoặc gọi một MCP server."""
     pass
 
 
@@ -35,6 +36,9 @@ class McpServerConnection:
 
     def __init__(self, name: str, command: str, args: Optional[List[str]] = None,
                 env: Optional[Dict[str, str]] = None):
+        """Ghi nhận cách khởi động một máy chủ MCP; chưa chạy tiến trình nào cho tới
+        lần dùng đầu tiên.
+        """
         self.name = name
         self.command = command
         self.args = list(args or [])
@@ -59,6 +63,7 @@ class McpServerConnection:
             raise McpServerError(f"MCP server '{self.name}' failed to start: {self._start_error}")
 
     def _run_loop(self) -> None:
+        """Thân luồng nền: dựng vòng lặp asyncio riêng và giữ nó chạy."""
         loop = asyncio.new_event_loop()
         self._loop = loop
         asyncio.set_event_loop(loop)
@@ -79,6 +84,7 @@ class McpServerConnection:
             loop.close()
 
     async def _connect(self) -> None:
+        """Khởi động tiến trình con và bắt tay phiên MCP."""
         from mcp import ClientSession, StdioServerParameters
         from mcp.client.stdio import stdio_client
 
@@ -93,6 +99,10 @@ class McpServerConnection:
         self._session = session
 
     async def _aclose(self) -> None:
+        """Đóng các context đã mở theo THỨ TỰ NGƯỢC.
+
+        Đóng xuôi sẽ đóng transport trước phiên và treo ở bước dọn dẹp.
+        """
         for cm in reversed(self._cm_stack):
             try:
                 await cm.__aexit__(None, None, None)
@@ -101,6 +111,7 @@ class McpServerConnection:
         self._cm_stack.clear()
 
     def stop(self) -> None:
+        """Dừng kết nối: tắt vòng lặp asyncio và chờ luồng nền kết thúc."""
         if self._loop is not None and self._loop.is_running():
             self._loop.call_soon_threadsafe(self._loop.stop)
         if self._thread is not None:
@@ -141,6 +152,10 @@ class McpServerConnection:
         return {"ok": ok, "output": output}
 
     def _run_coro(self, coro):
+        """Chạy một coroutine trên vòng lặp của kết nối và chờ kết quả.
+
+        Đây là cầu nối duy nhất giữa mã đồng bộ của app và phiên MCP bất đồng bộ.
+        """
         if self._loop is None:
             raise McpServerError(f"MCP server '{self.name}' is not connected")
         future = asyncio.run_coroutine_threadsafe(coro, self._loop)
@@ -166,6 +181,9 @@ def build_mcp_tools(servers: List[McpServerConnection]) -> Tuple[List[ToolSpec],
         return [], None
 
     def executor(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Bộ thực thi cho tool MCP: định tuyến theo tên về đúng server và ghi nhật ký
+        kiểm toán cho mỗi lần gọi.
+        """
         from . import audit_log
 
         server = routing.get(name)
diff --git a/core/model_pricing.py b/core/model_pricing.py
index 2ba8aac..984532a 100644
--- a/core/model_pricing.py
+++ b/core/model_pricing.py
@@ -65,6 +65,9 @@ _DIGITS = {"VND": 0, "JPY": 1, "USD": 4}
 
 
 def format_price(amount: float, ccy: str) -> str:
+    """Định dạng số tiền kèm ký hiệu tiền tệ, số chữ số thập phân theo từng loại
+    tiền (VND 0, JPY 1, USD 4).
+    """
     ccy = (ccy or "USD").upper()
     return f"{amount:,.{_DIGITS.get(ccy, 2)}f} {_SYMBOLS.get(ccy, '')}".strip()
 
@@ -99,14 +102,21 @@ def parse_price(text: Any) -> tuple:
 
 # ---- store ---------------------------------------------------------------
 def _bucket(config) -> Dict[str, Any]:
+    """Nhóm cấu hình ``model_pricing``; tự tạo nếu chưa có."""
     return config.data.setdefault("model_pricing", {})
 
 
 def list_entries(config) -> List[Dict[str, Any]]:
+    """Danh sách dòng đơn giá đã lưu (bản sao, sửa không ảnh hưởng cấu hình)."""
     return list(_bucket(config).get("entries", []) or [])
 
 
 def save_entries(config, entries: List[Dict[str, Any]]) -> None:
+    """Ghi lại toàn bộ bảng đơn giá và đồng bộ sang bộ tính chi phí.
+
+    Đồng bộ ngay tại đây để Tổng quan và Dashboard không hiện số tiền tính theo
+    bảng giá cũ.
+    """
     _bucket(config)["entries"] = [dict(e) for e in entries]
     sync_to_usage(config)      # keep the cost engine (Overview + Dashboard) in sync
 
@@ -115,6 +125,7 @@ def _norm_entry(model: str, ctx_len: str = "", max_out: str = "",
                 in_price=0.0, in_ccy: Optional[str] = None, in_unit: str = _DEFAULT_UNIT,
                 out_price=0.0, out_ccy: Optional[str] = None, out_unit: str = _DEFAULT_UNIT,
                 default_ccy: str = "USD") -> Dict[str, Any]:
+    """Chuẩn hoá một dòng đơn giá về đúng khuôn lưu trữ, điền mặc định cho ô trống."""
     return {
         "model": str(model).strip(),
         "context_length": str(ctx_len).strip(),
@@ -189,6 +200,7 @@ def format_tokens(n: int) -> str:
 
 
 def add_entry(config, entry: Dict[str, Any]) -> None:
+    """Thêm một dòng đơn giá; đã có model đó thì THAY THẾ chứ không thêm trùng."""
     entries = list_entries(config)
     entries = [e for e in entries if e.get("model") != entry.get("model")]  # replace same model
     entries.append(entry)
@@ -253,6 +265,7 @@ def import_table(path: str | Path, default_ccy: str = "USD") -> List[Dict[str, A
 
 
 def _rows_from_xlsx(path: Path) -> List[List[Any]]:
+    """Đọc các dòng từ file Excel (lấy giá trị đã tính, không lấy công thức)."""
     from openpyxl import load_workbook
     try:
         wb = load_workbook(str(path), data_only=True)
@@ -263,6 +276,7 @@ def _rows_from_xlsx(path: Path) -> List[List[Any]]:
 
 
 def _rows_from_csv(path: Path) -> List[List[Any]]:
+    """Đọc các dòng từ file CSV, chấp nhận BOM của Excel."""
     try:
         text = path.read_text(encoding="utf-8-sig")
     except OSError as exc:
diff --git a/core/ms365_auth.py b/core/ms365_auth.py
index 319bd52..693640e 100644
--- a/core/ms365_auth.py
+++ b/core/ms365_auth.py
@@ -57,10 +57,12 @@ SCOPES: List[str] = [
 
 
 class Ms365AuthError(Exception):
+    """Lỗi khi đăng nhập hoặc lấy token Microsoft 365."""
     pass
 
 
 def _load_cache():
+    """Nạp kho token đã lưu từ đĩa (nếu có)."""
     import msal
 
     cache = msal.SerializableTokenCache()
@@ -84,6 +86,7 @@ def _load_cache():
 
 
 def _save_cache(cache) -> None:
+    """Ghi kho token xuống đĩa, chỉ khi nó thật sự thay đổi."""
     if not cache.has_state_changed:
         return
     serialized = cache.serialize()
@@ -105,6 +108,9 @@ def _save_cache(cache) -> None:
 
 
 def _app(tenant_id: str, client_id: str):
+    """Dựng ứng dụng MSAL cho tenant/client đã cấu hình; thiếu ``msal`` thì báo lỗi
+    kèm hướng dẫn cài.
+    """
     try:
         import msal
     except ImportError as exc:
@@ -192,6 +198,7 @@ def get_access_token(tenant_id: str, client_id: str) -> str:
 # The UI calls these with no args for the "connect like Claude" flow; they read
 # the optional config overrides so a custom Azure app still works.
 def _ids(config=None):
+    """Cặp (tenant_id, client_id) đọc từ cấu hình MS365."""
     ms365 = (config.ms365 if config is not None else {}) or {}
     return ms365.get("tenant_id", ""), ms365.get("client_id", "")
 
@@ -203,6 +210,7 @@ def current_identity(config=None) -> str:
 
 
 def is_signed_in(config=None) -> bool:
+    """Đã có tài khoản MS365 đăng nhập sẵn hay chưa."""
     return signed_in_account(*_ids(config)) is not None
 
 
@@ -213,10 +221,12 @@ def sign_in(on_code: Callable[[dict], None], config=None) -> dict:
 
 
 def sign_out_default(config=None) -> None:
+    """Đăng xuất tài khoản MS365 theo cấu hình hiện tại."""
     sign_out(*_ids(config))
 
 
 def sign_out(tenant_id: str, client_id: str) -> None:
+    """Đăng xuất và xoá token của một tenant/client khỏi kho."""
     try:
         app, cache = _app(tenant_id, client_id)
         for acc in app.get_accounts():
diff --git a/core/ms365_graph.py b/core/ms365_graph.py
index acf1ab0..2b1fb1f 100644
--- a/core/ms365_graph.py
+++ b/core/ms365_graph.py
@@ -22,14 +22,17 @@ TIMEOUT = 30
 
 
 class Ms365GraphError(Exception):
+    """Lỗi khi gọi Microsoft Graph API."""
     pass
 
 
 class TeamsLinkError(Exception):
+    """Link Teams không phân giải được thành team/channel/chat hợp lệ."""
     pass
 
 
 def _headers(token: str, extra: Optional[dict] = None) -> Dict[str, str]:
+    """Header cho một lượt gọi Graph: Bearer token cộng phần thêm (nếu có)."""
     h = {"Authorization": f"Bearer {token}"}
     if extra:
         h.update(extra)
@@ -37,6 +40,9 @@ def _headers(token: str, extra: Optional[dict] = None) -> Dict[str, str]:
 
 
 def _request(method: str, url: str, token: str, **kwargs) -> requests.Response:
+    """Gọi Graph API, tự ghép ``GRAPH_BASE`` cho đường dẫn tương đối và đổi lỗi HTTP
+    thành :class:`Ms365GraphError` kèm thông điệp đọc được.
+    """
     if not url.startswith("http"):
         url = f"{GRAPH_BASE}{url}"
     headers = _headers(token, kwargs.pop("headers", None))
@@ -73,6 +79,7 @@ def _path_segment(path: str) -> str:
 
 # ---- Outlook ---------------------------------------------------------------
 def list_mail(token: str, top: int = 10, folder: str = "inbox") -> List[dict]:
+    """Danh sách thư trong một thư mục hộp thư (mặc định Inbox)."""
     resp = _request("GET", f"/me/mailFolders/{quote(folder)}/messages"
                             f"?$top={int(top)}&$select=subject,from,receivedDateTime,bodyPreview,webLink",
                      token)
@@ -80,6 +87,7 @@ def list_mail(token: str, top: int = 10, folder: str = "inbox") -> List[dict]:
 
 
 def send_mail(token: str, to: str, subject: str, body: str) -> None:
+    """Gửi một email qua tài khoản đang đăng nhập."""
     payload = {
         "message": {
             "subject": subject,
@@ -91,6 +99,7 @@ def send_mail(token: str, to: str, subject: str, body: str) -> None:
 
 
 def list_calendar_events(token: str, top: int = 10) -> List[dict]:
+    """Danh sách sự kiện lịch sắp tới, xếp theo thời gian bắt đầu."""
     resp = _request("GET", f"/me/events?$top={int(top)}"
                             "&$select=subject,start,end,organizer,location&$orderby=start/dateTime",
                      token)
@@ -99,38 +108,45 @@ def list_calendar_events(token: str, top: int = 10) -> List[dict]:
 
 # ---- Teams ------------------------------------------------------------------
 def list_teams(token: str) -> List[dict]:
+    """Các team mà người dùng đang tham gia."""
     resp = _request("GET", "/me/joinedTeams", token)
     return resp.json().get("value", [])
 
 
 def list_channels(token: str, team_id: str) -> List[dict]:
+    """Các kênh trong một team."""
     resp = _request("GET", f"/teams/{quote(team_id)}/channels", token)
     return resp.json().get("value", [])
 
 
 def list_channel_messages(token: str, team_id: str, channel_id: str, top: int = 20) -> List[dict]:
+    """Tin nhắn gần đây trong một kênh."""
     resp = _request("GET", f"/teams/{quote(team_id)}/channels/{quote(channel_id)}/messages"
                             f"?$top={int(top)}", token)
     return resp.json().get("value", [])
 
 
 def send_channel_message(token: str, team_id: str, channel_id: str, text: str) -> None:
+    """Gửi tin nhắn vào một kênh Teams."""
     payload = {"body": {"content": text}}
     _request("POST", f"/teams/{quote(team_id)}/channels/{quote(channel_id)}/messages", token,
               json=payload)
 
 
 def get_channel(token: str, team_id: str, channel_id: str) -> dict:
+    """Thông tin một kênh Teams."""
     resp = _request("GET", f"/teams/{quote(team_id)}/channels/{quote(channel_id)}", token)
     return resp.json()
 
 
 def get_chat(token: str, chat_id: str) -> dict:
+    """Thông tin một cuộc trò chuyện Teams."""
     resp = _request("GET", f"/chats/{quote(chat_id)}", token)
     return resp.json()
 
 
 def send_chat_message(token: str, chat_id: str, text: str) -> None:
+    """Gửi tin nhắn vào một cuộc trò chuyện Teams."""
     _request("POST", f"/chats/{quote(chat_id)}/messages", token, json={"body": {"content": text}})
 
 
@@ -160,17 +176,20 @@ def parse_teams_link(url: str) -> Dict[str, str]:
 
 # ---- OneDrive -----------------------------------------------------------
 def list_onedrive_files(token: str, path: str = "") -> List[dict]:
+    """Liệt kê tệp/thư mục trong OneDrive; ``path`` rỗng là thư mục gốc."""
     url = "/me/drive/root/children" if not path else f"/me/drive/root:/{_path_segment(path)}:/children"
     resp = _request("GET", url, token)
     return resp.json().get("value", [])
 
 
 def read_onedrive_file(token: str, path: str, max_chars: int = 50_000) -> str:
+    """Đọc nội dung một tệp OneDrive dưới dạng văn bản, cắt ở ``max_chars``."""
     resp = _request("GET", f"/me/drive/root:/{_path_segment(path)}:/content", token)
     return resp.content.decode("utf-8", errors="replace")[:max_chars]
 
 
 def write_onedrive_file(token: str, path: str, content: str) -> dict:
+    """Ghi nội dung văn bản vào một tệp OneDrive (tạo mới hoặc ghi đè)."""
     resp = _request("PUT", f"/me/drive/root:/{_path_segment(path)}:/content", token,
                      data=content.encode("utf-8"),
                      headers={"Content-Type": "text/plain"})
@@ -197,11 +216,13 @@ def read_shared_file(token: str, share_url: str, max_chars: int = 50_000) -> str
 
 # ---- SharePoint --------------------------------------------------------
 def list_sharepoint_sites(token: str, query: str) -> List[dict]:
+    """Tìm site SharePoint theo từ khoá."""
     resp = _request("GET", f"/sites?search={quote(query)}", token)
     return resp.json().get("value", [])
 
 
 def list_sharepoint_files(token: str, site_id: str, path: str = "") -> List[dict]:
+    """Liệt kê tệp/thư mục trong thư viện tài liệu của một site SharePoint."""
     url = (f"/sites/{quote(site_id)}/drive/root/children" if not path
            else f"/sites/{quote(site_id)}/drive/root:/{_path_segment(path)}:/children")
     resp = _request("GET", url, token)
@@ -210,18 +231,21 @@ def list_sharepoint_files(token: str, site_id: str, path: str = "") -> List[dict
 
 # ---- Teams meeting transcripts ------------------------------------------
 def find_online_meeting(token: str, join_url: str) -> List[dict]:
+    """Tìm cuộc họp online theo link tham gia."""
     resp = _request("GET", f"/me/onlineMeetings?$filter=JoinWebUrl eq '{quote(join_url, safe='')}'",
                      token)
     return resp.json().get("value", [])
 
 
 def list_meeting_transcripts(token: str, meeting_id: str) -> List[dict]:
+    """Danh sách bản ghi lời thoại của một cuộc họp."""
     resp = _request("GET", f"/me/onlineMeetings/{quote(meeting_id)}/transcripts", token)
     return resp.json().get("value", [])
 
 
 def get_meeting_transcript_content(token: str, meeting_id: str, transcript_id: str,
                                    max_chars: int = 50_000) -> str:
+    """Nội dung một bản ghi lời thoại, cắt ở ``max_chars``."""
     resp = _request(
         "GET",
         f"/me/onlineMeetings/{quote(meeting_id)}/transcripts/{quote(transcript_id)}/content"
diff --git a/core/ms365_local.py b/core/ms365_local.py
index 0bdab5a..f370a7d 100644
--- a/core/ms365_local.py
+++ b/core/ms365_local.py
@@ -28,10 +28,12 @@ _PREFIX = "ms365_local"
 
 
 def _roots() -> List[Path]:
+    """Mọi thư mục OneDrive tìm thấy trên máy."""
     return paths.detect_onedrive_roots()
 
 
 def _primary_root() -> Optional[Path]:
+    """Thư mục OneDrive chính; ``None`` nếu không có."""
     return paths.primary_onedrive_root()
 
 
@@ -45,6 +47,7 @@ def _resolve_under(root: Path, rel: str) -> Path:
 
 
 def _list_dir(base: Path, rel: str) -> dict:
+    """Liệt kê nội dung một thư mục con của OneDrive, chặn thoát ra ngoài gốc."""
     target = _resolve_under(base, rel)
     if not target.exists():
         raise FileNotFoundError(f"Not found: {rel or '.'}")
@@ -60,6 +63,7 @@ def _list_dir(base: Path, rel: str) -> dict:
 
 
 def _read_file(base: Path, rel: str) -> str:
+    """Đọc một tệp trong OneDrive dưới dạng văn bản, chặn thoát ra ngoài gốc."""
     target = _resolve_under(base, rel)
     if not target.is_file():
         raise FileNotFoundError(f"Not a file: {rel}")
@@ -68,6 +72,7 @@ def _read_file(base: Path, rel: str) -> str:
 
 
 def _write_file(base: Path, rel: str, content: str) -> dict:
+    """Ghi một tệp trong OneDrive, tự tạo thư mục cha, chặn thoát ra ngoài gốc."""
     target = _resolve_under(base, rel)
     target.parent.mkdir(parents=True, exist_ok=True)
     target.write_text(content or "", encoding="utf-8")
@@ -125,6 +130,9 @@ def build_ms365_local_tools(config) -> Tuple[List[ToolSpec], Optional[Callable[[
         ]
 
     def executor(name: str, args: dict) -> dict:
+        """Bộ thực thi tool MS365 cục bộ (đọc/ghi thẳng thư mục OneDrive đồng bộ trên
+        máy, không cần đăng nhập Graph), ghi nhật ký kiểm toán cho mỗi lần gọi.
+        """
         ok = False
         detail = ""
         try:
diff --git a/core/ms365_tools.py b/core/ms365_tools.py
index 7a5c086..78e15d3 100644
--- a/core/ms365_tools.py
+++ b/core/ms365_tools.py
@@ -168,6 +168,9 @@ _MAX_OUTPUT_CHARS = 20_000
 
 
 def _dump(data: Any) -> str:
+    """Kết quả tool dưới dạng JSON đã cắt ở ``_MAX_OUTPUT_CHARS`` — một hộp thư đầy
+    sẽ nuốt trọn cửa sổ ngữ cảnh nếu trả về nguyên vẹn.
+    """
     text = json.dumps(data, ensure_ascii=False, indent=2, default=str)
     if len(text) > _MAX_OUTPUT_CHARS:
         text = text[:_MAX_OUTPUT_CHARS] + f"\n…(truncated to {_MAX_OUTPUT_CHARS} chars)…"
@@ -197,6 +200,9 @@ def build_ms365_tools(config) -> Tuple[List[ToolSpec], Optional[Callable[[str, d
         return [], None
 
     def executor(name: str, args: dict) -> dict:
+        """Bộ thực thi các tool MS365 (mail, lịch, Teams, OneDrive, SharePoint), gói lỗi
+        thành kết quả thay vì ném ra.
+        """
         args = args or {}
         try:
             token = get_access_token(tenant_id, client_id)
diff --git a/core/permissions.py b/core/permissions.py
index c51d183..6903e86 100644
--- a/core/permissions.py
+++ b/core/permissions.py
@@ -13,8 +13,19 @@ RequestFn = Callable[[Dict[str, Any]], None]
 
 
 class PermissionGate:
+    """Cổng phê duyệt tool: chặn lượt chạy lại và chờ người dùng đồng ý.
+
+    Ba chế độ: 'auto' cho qua hết, 'confirm' hỏi trước mỗi lệnh có rủi ro, và
+    'deny' chặn thẳng. Dùng ``threading.Event`` để luồng nền đứng chờ trong khi
+    luồng giao diện hiện hộp thoại.
+    """
     def __init__(self, mode: str = "confirm", on_request: Optional[RequestFn] = None,
                 agent_role: str = ""):
+        """``mode`` quyết định cách xử: hỏi, cho qua hết, hay chặn hết.
+
+        ``on_request`` là hàm hiện hộp thoại; để None (không có giao diện) thì cổng
+        rơi về quyết định mặc định của ``mode`` thay vì treo mãi.
+        """
         self.mode = mode
         self.on_request = on_request
         self.agent_role = agent_role
@@ -22,6 +33,7 @@ class PermissionGate:
         self._approved = False
 
     def set_mode(self, mode: str) -> None:
+        """Đổi chế độ phê duyệt giữa chừng."""
         self.mode = mode
 
     def request(self, action: Dict[str, Any]) -> bool:
@@ -43,6 +55,7 @@ class PermissionGate:
         return self._approved
 
     def resolve(self, approved: bool) -> None:
+        """Người dùng đã trả lời: ghi kết quả và đánh thức luồng đang chờ."""
         self._approved = approved
         self._event.set()
 
diff --git a/core/pptx_edit.py b/core/pptx_edit.py
index b895213..770225a 100644
--- a/core/pptx_edit.py
+++ b/core/pptx_edit.py
@@ -37,6 +37,7 @@ _KEEP_PREFIX = "("   # image values like "(keep …)" mean "don't change"
 
 
 def is_available() -> bool:
+    """Máy đã cài ``python-pptx`` chưa — không có thì mọi tính năng PowerPoint tắt."""
     try:
         import pptx  # noqa: F401
         return True
@@ -45,10 +46,12 @@ def is_available() -> bool:
 
 
 def _in(emu) -> float:
+    """Đổi đơn vị EMU của Office sang inch, làm tròn 2 chữ số."""
     return round((emu or 0) / _EMU_PER_IN, 2)
 
 
 def _kind(shape) -> str:
+    """Loại hình khối trong slide: ảnh, bảng, biểu đồ hay hộp văn bản."""
     from pptx.enum.shapes import MSO_SHAPE_TYPE
     try:
         if shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
@@ -182,6 +185,11 @@ def _apply_font(shape, spec: str) -> bool:
 
 
 def _parse(text: str) -> Dict[Tuple[int, int], dict]:
+    """Đọc dạng văn bản đánh dấu của slide trở lại thành cấu trúc.
+
+    Đây là khuôn trung gian giữa PowerPoint và ô soạn thảo: người dùng (và AI)
+    sửa văn bản, hàm này dựng lại thành thao tác trên deck.
+    """
     blocks: Dict[Tuple[int, int], dict] = {}
     cur: Tuple[int, int] | None = None
     fields: dict = {}
@@ -189,6 +197,7 @@ def _parse(text: str) -> Dict[Tuple[int, int], dict]:
     textbuf: List[str] = []
 
     def _flush():
+        """Chốt khối đang đọc dở và đưa vào kết quả."""
         if cur is not None:
             if in_text:
                 fields["text"] = "\n".join(textbuf).strip("\n")
@@ -221,6 +230,7 @@ def _parse(text: str) -> Dict[Tuple[int, int], dict]:
 
 
 def _pair(val: str):
+    """Đọc chuỗi 'a, b' thành cặp số (dùng cho toạ độ và kích thước)."""
     try:
         a, b = (x.strip() for x in val.split(",", 1))
         return float(a), float(b)
diff --git a/core/projects.py b/core/projects.py
index 185d949..1cb11ac 100644
--- a/core/projects.py
+++ b/core/projects.py
@@ -44,6 +44,11 @@ STARTER_PROJECT_NAME = "My Workspace"
 
 @dataclass
 class Project:
+    """Một project: id, tên, mô tả, chỉ dẫn chung và thư mục sandbox.
+
+    Chỉ dẫn chung được chèn vào MỌI lượt chat thuộc project, nên đây là chỗ đặt
+    bối cảnh dùng lại thay vì gõ lại ở từng tin nhắn.
+    """
     project_id: str
     name: str
     description: str = ""
@@ -92,6 +97,7 @@ def ensure_starter_project(directory: Path = None) -> Project:
 
 
 def _slugify(name: str) -> str:
+    """Định danh an toàn cho tên file, suy từ tên project."""
     s = "".join(c if (c.isalnum() or c in "-_") else "-" for c in name.strip().lower())
     s = "-".join(filter(None, s.split("-")))
     return s or "project"
@@ -115,6 +121,7 @@ def new_project(name: str, description: str = "", instructions: str = "",
 
 
 def save_project(project: Project, directory: Path = None) -> Path:
+    """Ghi một project ra ``<project_id>.json`` (ghi nguyên tử)."""
     directory = directory or PROJECTS_DIR
     path = directory / f"{project.project_id}.json"
     # R06-T02: atomic write — a crash/kill between truncate and write used to
diff --git a/core/routing/classifier.py b/core/routing/classifier.py
index a5ea923..375e08d 100644
--- a/core/routing/classifier.py
+++ b/core/routing/classifier.py
@@ -73,6 +73,11 @@ LLMClassifier = Callable[[str], str]
 
 
 def _heuristic_scores(text: str) -> dict[TaskType, int]:
+    """Chấm điểm loại việc bằng từ khoá, không cần gọi model.
+
+    Bước lọc rẻ đứng trước bộ phân loại bằng AI: phần lớn câu hỏi phân loại được
+    ngay tại đây mà không tốn lượt gọi nào.
+    """
     low = (text or "").lower()
     scores: dict[TaskType, int] = {tt: 0 for tt in TaskType}
     for tt, entries in _COMPILED.items():
diff --git a/core/routing/clients.py b/core/routing/clients.py
index f358051..f01ba53 100644
--- a/core/routing/clients.py
+++ b/core/routing/clients.py
@@ -25,6 +25,7 @@ class CompletionResult:
 
     @property
     def ok(self) -> bool:
+        """Lượt dò có thành công không (không có lỗi)."""
         return self.error is None
 
 
@@ -37,6 +38,7 @@ class ProbeClient(Protocol):
         model_id: str,
         messages: List[Dict[str, Any]],
     ) -> CompletionResult:
+        """Gọi một model và trả về kết quả kèm số token, độ trễ và lỗi (nếu có)."""
         ...
 
 
@@ -59,6 +61,7 @@ class AppProbeClient:
     """
 
     def __init__(self, ctx: Any) -> None:
+        """Giữ ``AppContext`` để dựng provider lúc cần thăm dò."""
         self.ctx = ctx
 
     def complete(
@@ -67,6 +70,9 @@ class AppProbeClient:
         model_id: str,
         messages: List[Dict[str, Any]],
     ) -> CompletionResult:
+        """Gọi model qua provider thật; lỗi được gói vào kết quả chứ không ném ra —
+        một model hỏng không được làm dừng cả lượt chấm điểm danh mục.
+        """
         try:
             prov = self.ctx.build_provider_for(provider, model_id or None)
             # Non-streaming: no on_text/on_reasoning callbacks. cancel=None.
diff --git a/core/routing/models.py b/core/routing/models.py
index 9a66192..7ec14f4 100644
--- a/core/routing/models.py
+++ b/core/routing/models.py
@@ -138,6 +138,7 @@ class ModelAssessment(BaseModel):
 
     @property
     def key(self) -> str:
+        """Khoá định danh của model được chấm điểm (provider + model id)."""
         return self.metadata.key
 
     def fit_for(self, task_type: TaskType) -> float:
diff --git a/core/routing/orchestrator.py b/core/routing/orchestrator.py
index a76f57d..2651f59 100644
--- a/core/routing/orchestrator.py
+++ b/core/routing/orchestrator.py
@@ -126,6 +126,9 @@ def check_and_update(
     call_count = {"n": 0}
 
     def _tick() -> None:
+        """Một nhịp đếm trong lúc chờ người dùng xác nhận đổi model — đếm lùi và tự
+        quyết định khi hết giờ.
+        """
         call_count["n"] += 1
 
     pairs = [(p, m) for (p, m, _tier) in candidates]
diff --git a/core/routing/prober.py b/core/routing/prober.py
index a2c71a5..0ab20fc 100644
--- a/core/routing/prober.py
+++ b/core/routing/prober.py
@@ -70,6 +70,7 @@ _SCORE_RE = re.compile(r'"score"\s*:\s*([0-9]*\.?[0-9]+)')
 
 
 def _clamp01(x: float) -> float:
+    """Chặn một số về khoảng 0..1."""
     return min(1.0, max(0.0, float(x)))
 
 
@@ -108,6 +109,10 @@ def make_judge(
     """
 
     def judge(task_type: TaskType, prompt: str, answer: str) -> float:
+        """Chấm điểm câu trả lời của một model theo rubric, trả về điểm 0..1.
+
+        Cắt câu trả lời ở 4000 ký tự để một lượt chấm không tự nó tràn ngữ cảnh.
+        """
         rubric = _JUDGE_RUBRIC.format(
             task=task_type.value, prompt=prompt, answer=(answer or "")[:4000]
         )
@@ -160,11 +165,17 @@ class _PerProviderSemaphores:
     """Lazily-created, per-provider bounded semaphores for rate-limit safety."""
 
     def __init__(self, limit: int) -> None:
+        """Giới hạn số lượt thăm dò song song TRÊN MỖI provider.
+
+        Đếm riêng từng provider chứ không đếm chung: một provider chậm không được
+        phép chiếm hết suất của những provider còn lại.
+        """
         self._limit = max(1, int(limit))
         self._sems: Dict[str, threading.Semaphore] = {}
         self._lock = threading.Lock()
 
     def get(self, provider: str) -> threading.Semaphore:
+        """Semaphore của một provider, tạo lười ở lần dùng đầu."""
         with self._lock:
             sem = self._sems.get(provider)
             if sem is None:
@@ -201,6 +212,7 @@ def probe_candidates(
     results_lock = threading.Lock()
 
     def _one(provider: str, model_id: str, task_type: TaskType) -> None:
+        """Dò một cặp (provider, model) cho một loại việc, tôn trọng giới hạn song song."""
         sem = sems.get(provider)
         with sem:
             if call_counter is not None:
diff --git a/core/routing/scheduler.py b/core/routing/scheduler.py
index dd0e0a6..bc456d8 100644
--- a/core/routing/scheduler.py
+++ b/core/routing/scheduler.py
@@ -33,6 +33,7 @@ class RoutingScheduler(QObject):
     reassess_finished = Signal(int)  # number of models assessed
 
     def __init__(self, ctx: Any, service: Any, parent: Optional[QObject] = None) -> None:
+        """Dựng bộ hẹn giờ chạy thăm dò định kỳ. Chưa chạy cho tới khi gọi ``start()``."""
         super().__init__(parent)
         self.ctx = ctx
         self.service = service
@@ -49,16 +50,19 @@ class RoutingScheduler(QObject):
         self._timer.start()
 
     def stop(self) -> None:
+        """Dừng hẹn giờ."""
         self._timer.stop()
 
     # -- tick ----------------------------------------------------------- #
     def _interval_hours(self) -> float:
+        """Chu kỳ chấm điểm lại, tính bằng giờ; giá trị lạ thì coi như tắt."""
         try:
             return float(self.ctx.config.routing.get("reassess_interval_hours", 24) or 0)
         except Exception:  # noqa: BLE001
             return 24.0
 
     def _hours_since_last(self) -> Optional[float]:
+        """Số giờ kể từ lần chấm điểm gần nhất; ``None`` nếu chưa chấm lần nào."""
         last = self.service.store.last_updated()
         if not last:
             return None  # never assessed
@@ -87,6 +91,11 @@ class RoutingScheduler(QObject):
         return False
 
     def is_due(self) -> bool:
+        """Đã đến lúc chấm điểm lại chưa.
+
+        Tắt định tuyến ở mọi bề mặt thì KHÔNG dò — dò model là lượt gọi có tính phí,
+        không được tiêu tiền cho một tính năng người dùng đã tắt.
+        """
         if not self._routing_enabled_anywhere():
             return False  # routing off everywhere → don't probe (would be wasted cost)
         interval = self._interval_hours()
@@ -111,6 +120,7 @@ class RoutingScheduler(QObject):
         self.reassess_started.emit()
 
         def _done(result) -> None:
+            """Chấm điểm xong: báo ra ngoài số model đã đánh giá."""
             self.reassess_finished.emit(len(result or {}))
 
         self.service.reassess_background(on_done=_done)
diff --git a/core/routing/selector.py b/core/routing/selector.py
index 8aed7a9..d0b6a1e 100644
--- a/core/routing/selector.py
+++ b/core/routing/selector.py
@@ -27,6 +27,7 @@ class RankedCandidate:
 
     @property
     def key(self) -> str:
+        """Khoá định danh của ứng viên (provider + model)."""
         return self.assessment.key
 
 
@@ -40,6 +41,7 @@ class Ranking:
 
     @property
     def best(self) -> Optional[RankedCandidate]:
+        """Ứng viên đứng đầu; ``None`` nếu không có ứng viên nào."""
         return self.ranked[0] if self.ranked else None
 
     def score_of(self, key: str) -> float:
@@ -66,6 +68,7 @@ class Ranking:
 
 
 def _has_capabilities(assessment: ModelAssessment, required: Set[str]) -> bool:
+    """Model này có đủ mọi năng lực mà lượt chạy đòi hỏi không."""
     return required.issubset(assessment.metadata.capabilities)
 
 
@@ -99,6 +102,10 @@ def rank_models(
         scored.append(RankedCandidate(assessment=a, score=score))
 
     def _sort_key(c: RankedCandidate):
+        """Khoá sắp xếp ứng viên: điểm cao trước, cùng điểm thì rẻ hơn trước.
+
+        Model chưa biết giá bị xếp cuối (coi như vô cùng đắt) chứ không phải miễn phí.
+        """
         cost = c.assessment.metadata.avg_cost_per_1k
         cost = cost if cost is not None else float("inf")
         # score desc, then cheaper, then model id for determinism.
diff --git a/core/routing/service.py b/core/routing/service.py
index 7835791..e96dc8b 100644
--- a/core/routing/service.py
+++ b/core/routing/service.py
@@ -64,6 +64,7 @@ class RouteResult:
 
     @property
     def should_switch(self) -> bool:
+        """Có nên đổi sang model khác cho lượt này không."""
         return self.decision.should_switch
 
     @property
@@ -89,6 +90,9 @@ class RoutingService:
         client: Optional[ProbeClient] = None,
         clock: Optional[Callable[[], float]] = None,
     ) -> None:
+        """``store``/``client``/``clock`` đều tiêm được: test thay đồng hồ để tua thời
+        gian mà không phải chờ thật, và thay client để không gọi mạng.
+        """
         self.ctx = ctx
         self.store = store or AssessmentStore()
         self._client = client  # None → lazily build AppProbeClient(ctx)
@@ -100,6 +104,7 @@ class RoutingService:
     # -- config helpers ------------------------------------------------- #
     @property
     def _routing_cfg(self) -> Dict[str, Any]:
+        """Nhóm cấu hình định tuyến hiện tại."""
         return self.ctx.config.routing
 
     def get_routing_config(self) -> Dict[str, Any]:
@@ -125,6 +130,7 @@ class RoutingService:
         return dict(cfg)
 
     def _policy(self) -> Policy:
+        """Chính sách chấm điểm đang chọn; giá trị lạ thì rơi về 'balanced'."""
         raw = (self._routing_cfg.get("policy") or "balanced").lower()
         try:
             return Policy(raw)
@@ -132,6 +138,7 @@ class RoutingService:
             return Policy.BALANCED
 
     def _client_or_build(self) -> ProbeClient:
+        """Client dò model, dựng lười để chưa bật định tuyến thì không tốn gì."""
         if self._client is None:
             self._client = AppProbeClient(self.ctx)
         return self._client
@@ -160,6 +167,9 @@ class RoutingService:
         seen = set()
 
         def _add(provider: str, model_id: str, tier: Optional[str]) -> None:
+            """Thêm một ứng viên (provider, model) vào danh sách, bỏ qua mục thiếu thông tin
+            hoặc trùng.
+            """
             if not provider or not model_id:
                 return
             key = candidate_key(provider, model_id)
@@ -246,6 +256,11 @@ class RoutingService:
     ) -> threading.Thread:
         """Run :meth:`reassess` on a daemon thread (non-Qt, headless-safe)."""
         def _run() -> None:
+            """Chạy nền: chấm điểm lại danh mục model.
+
+            Nuốt mọi ngoại lệ có chủ ý — một lần chấm điểm hỏng không được phép làm
+            chết ứng dụng, vì đây là việc chạy ngầm người dùng không yêu cầu.
+            """
             try:
                 result = self.reassess(policy)
             except Exception:  # noqa: BLE001 — never let a reassess crash the app
@@ -262,10 +277,12 @@ class RoutingService:
         return t
 
     def is_reassessing(self) -> bool:
+        """Có đang chấm điểm lại danh mục model hay không."""
         return self._reassessing
 
     # -- query ---------------------------------------------------------- #
     def assessments(self) -> Dict[str, ModelAssessment]:
+        """Bảng điểm model đã lưu, đọc từ kho đánh giá."""
         return self.store.load()
 
     def status(self) -> Dict[str, Any]:
@@ -347,6 +364,7 @@ class RoutingService:
         return self.pending.resolve(request_id, approve, run)
 
     def get_pending(self, request_id: str) -> Optional[PendingSwitch]:
+        """Đề nghị đổi model đang chờ người dùng xác nhận; ``None`` nếu không có."""
         return self.pending.get(request_id)
 
     def sweep_pending(self) -> List[str]:
diff --git a/core/routing/store.py b/core/routing/store.py
index a24a061..84b60f6 100644
--- a/core/routing/store.py
+++ b/core/routing/store.py
@@ -68,6 +68,11 @@ class AssessmentStore:
         store_path: Optional[Path] = None,
         history_dir: Optional[Path] = None,
     ) -> None:
+        """``store_path`` để None thì dùng file mặc định trong thư mục cấu hình.
+
+        Import ``CONFIG_DIR`` muộn ngay trong thân hàm: nạp nó lúc import module sẽ
+        kéo theo cả cây cấu hình vào mọi test dùng lớp này.
+        """
         if store_path is None:
             from ...config import CONFIG_DIR  # lazy: avoids import cost in tests
             store_path = CONFIG_DIR / _DEFAULT_STORE_NAME
@@ -107,9 +112,11 @@ class AssessmentStore:
         return out
 
     def last_updated(self) -> Optional[str]:
+        """Mốc thời gian lần chấm điểm gần nhất; ``None`` nếu chưa chấm lần nào."""
         return self.load_raw().get("last_updated")
 
     def policy(self) -> str:
+        """Chính sách chấm điểm đã lưu; chưa có thì mặc định 'balanced'."""
         return self.load_raw().get("policy") or Policy.BALANCED.value
 
     # -- write ---------------------------------------------------------- #
diff --git a/core/routing/switch_controller.py b/core/routing/switch_controller.py
index 77346f5..d3a6e9b 100644
--- a/core/routing/switch_controller.py
+++ b/core/routing/switch_controller.py
@@ -141,6 +141,7 @@ class PendingSwitchRegistry:
     _RESOLVE_WAIT_SEC = 600.0
 
     def __init__(self, clock: Callable[[], float] = time.time) -> None:
+        """``clock`` tiêm được để test kiểm hết hạn mà không phải chờ thật."""
         self._items: Dict[str, PendingSwitch] = {}
         self._events: Dict[str, threading.Event] = {}
         self._running: Set[str] = set()
@@ -180,6 +181,7 @@ class PendingSwitchRegistry:
             return ps
 
     def _maybe_expire_locked(self, ps: PendingSwitch) -> None:
+        """Đánh dấu hết hạn nếu đã quá hạn chờ. Gọi trong lúc đang giữ khoá."""
         if ps.status == SwitchStatus.PENDING and self._clock() >= ps.expires_at:
             ps.status = SwitchStatus.EXPIRED
 
@@ -270,6 +272,7 @@ class PendingSwitchRegistry:
         return removed
 
     def pending_ids(self) -> List[str]:
+        """Id các đề nghị còn đang chờ (đã loại những cái vừa hết hạn)."""
         with self._lock:
             return [
                 rid for rid, ps in self._items.items()
diff --git a/core/sandbox_manager.py b/core/sandbox_manager.py
index 61a01fd..6264106 100644
--- a/core/sandbox_manager.py
+++ b/core/sandbox_manager.py
@@ -44,6 +44,7 @@ class SandboxManager:
     """Central sandbox manager that selects and routes to the right backend."""
 
     def __init__(self, config: Optional[ExecutionConfig] = None):
+        """Chưa dựng backend nào — chúng được tạo muộn, lúc thật sự cần chạy lệnh."""
         self.config = config or ExecutionConfig()
         self._backends: Dict[str, Any] = {}
 
diff --git a/core/skills.py b/core/skills.py
index 97f827d..2951dba 100644
--- a/core/skills.py
+++ b/core/skills.py
@@ -36,6 +36,7 @@ LIBRARY_DIR = Path(__file__).resolve().parent.parent / "skill_library"
 
 @dataclass
 class Skill:
+    """Một Skill: tên, mô tả, phần chỉ dẫn chèn vào prompt, và cờ bật/tắt."""
     name: str
     description: str = ""
     instructions: str = ""
@@ -43,12 +44,14 @@ class Skill:
 
     @property
     def slug(self) -> str:
+        """Định danh an toàn cho tên file, suy từ tên skill."""
         keep = "-_"
         s = "".join(c if (c.isalnum() or c in keep) else "-" for c in self.name.strip().lower())
         return "-".join(filter(None, s.split("-"))) or "skill"
 
 
 def skills_dir() -> Path:
+    """Thư mục chứa skill của người dùng."""
     return SKILLS_DIR
 
 
@@ -180,6 +183,9 @@ def builtin_skills() -> List[Skill]:
 
 
 def _builtin_slugs() -> set[str]:
+    """Tập slug của các skill dựng sẵn — dùng để không gieo trùng và không cho sửa
+    chúng như skill thường.
+    """
     return {s.slug for s in builtin_skills()}
 
 
@@ -277,6 +283,11 @@ def list_skills(directory: Path | None = None) -> List[Skill]:
 
 
 def save_skill(skill: Skill, directory: Path | None = None, old_name: str = "") -> Path:
+    """Ghi một skill xuống đĩa.
+
+    Đổi tên thì XOÁ file cũ trước — tên file suy từ tên skill, không xoá sẽ để
+    lại một bản sao dưới tên cũ.
+    """
     directory = directory or SKILLS_DIR
     directory.mkdir(parents=True, exist_ok=True)
     if old_name and old_name != skill.name:
@@ -287,6 +298,7 @@ def save_skill(skill: Skill, directory: Path | None = None, old_name: str = "")
 
 
 def delete_skill(name: str, directory: Path | None = None) -> None:
+    """Xoá file skill theo tên; không có thì bỏ qua."""
     directory = directory or SKILLS_DIR
     path = directory / f"{Skill(name=name).slug}.json"
     if path.exists():
@@ -304,6 +316,9 @@ def _load_skill_from_zip(path: Path) -> "Skill | None":
     import zipfile
 
     def _rank(n: str) -> int:
+        """Thứ tự ưu tiên khi gói zip có nhiều file Markdown: ``skill.md`` trước, rồi
+        tới file ở gốc gói, cuối cùng mới tới file nằm sâu.
+        """
         low = n.lower()
         if low.endswith("skill.md"):
             return 0
diff --git a/core/structure_graph.py b/core/structure_graph.py
index e23463a..03e3905 100644
--- a/core/structure_graph.py
+++ b/core/structure_graph.py
@@ -35,6 +35,7 @@ MAX_JSON_KEYS_PER_LEVEL = 200  # cap per object, so one huge JSON can't flood th
 
 @dataclass
 class GNode:
+    """Một node trong đồ thị cấu trúc: thư mục, tệp, lớp, hàm, phương thức hay mục tài liệu."""
     id: str
     label: str
     kind: str          # dir | file | class | function | method | module | section
@@ -44,6 +45,7 @@ class GNode:
 
 @dataclass
 class GEdge:
+    """Một cạnh trong đồ thị cấu trúc, kèm LOẠI quan hệ (chứa / định nghĩa / import…)."""
     source: str
     target: str
     type: str = ""     # contains | defines | method | imports | subsection
@@ -51,6 +53,11 @@ class GEdge:
 
 @dataclass
 class StructureGraph:
+    """Đồ thị cấu trúc mã nguồn, có trần số node/cạnh.
+
+    Chạm trần thì bật cờ ``truncated`` và ngừng thêm — đồ thị quá lớn làm treo
+    khung vẽ, thà hiện một phần kèm cảnh báo còn hơn đứng hình.
+    """
     nodes: List[GNode] = field(default_factory=list)
     edges: List[GEdge] = field(default_factory=list)
     truncated: bool = False
@@ -58,9 +65,13 @@ class StructureGraph:
     max_edges: int = 0   # 0 = unlimited
 
     def __post_init__(self):
+        """Dựng sẵn tập id node để kiểm tra một cạnh có hợp lệ không trong thời gian
+        hằng số, thay vì quét cả danh sách node cho từng cạnh.
+        """
         self._ids = {n.id for n in self.nodes}
 
     def add_node(self, node: GNode) -> bool:
+        """Thêm một node; trả về ``False`` nếu trùng id hoặc đã chạm trần."""
         if node.id in self._ids:
             return False
         if self.max_nodes and len(self.nodes) >= self.max_nodes:
@@ -71,6 +82,7 @@ class StructureGraph:
         return True
 
     def add_edge(self, source: str, target: str, type_: str = "") -> None:
+        """Thêm một cạnh; bỏ qua nếu một trong hai đầu chưa có node, hoặc đã chạm trần."""
         if source in self._ids and target in self._ids:
             if self.max_edges and len(self.edges) >= self.max_edges:
                 self.truncated = True
@@ -78,6 +90,7 @@ class StructureGraph:
             self.edges.append(GEdge(source, target, type_))
 
     def has(self, node_id: str) -> bool:
+        """Đồ thị đã có node với id này chưa."""
         return node_id in self._ids
 
 
@@ -144,6 +157,7 @@ def _add_generic_file(graph: StructureGraph, dir_id: str, fpath: Path, root: Pat
 
 
 def _rel(path: Path, root: Path) -> str:
+    """Đường dẫn tương đối so với thư mục gốc; nằm ngoài gốc thì trả nguyên đường dẫn."""
     try:
         return str(path.relative_to(root))
     except ValueError:
@@ -151,6 +165,7 @@ def _rel(path: Path, root: Path) -> str:
 
 
 def _add_python_file(graph: StructureGraph, dir_id: str, fpath: Path, root: Path) -> None:
+    """Thêm một tệp Python vào đồ thị: node tệp, các lớp, hàm, phương thức và import."""
     file_id = f"file:{fpath}"
     if not graph.add_node(GNode(file_id, fpath.name, "file", _rel(fpath, root), str(fpath))):
         return
@@ -184,6 +199,7 @@ def _add_python_file(graph: StructureGraph, dir_id: str, fpath: Path, root: Path
 
 
 def _module_imports(tree: ast.AST) -> List[str]:
+    """Tên các module mà một cây AST import vào."""
     mods: List[str] = []
     for node in ast.walk(tree):
         if isinstance(node, ast.Import):
@@ -199,6 +215,7 @@ def _module_imports(tree: ast.AST) -> List[str]:
 
 
 def _add_doc_file(graph: StructureGraph, dir_id: str, fpath: Path, root: Path) -> None:
+    """Thêm một tệp tài liệu (Markdown…) vào đồ thị, tách theo cấp tiêu đề."""
     file_id = f"file:{fpath}"
     fp = str(fpath)
     if not graph.add_node(GNode(file_id, fpath.name, "file", _rel(fpath, root), fp)):
@@ -254,6 +271,7 @@ def _add_json_file(graph: StructureGraph, dir_id: str, fpath: Path, root: Path)
 
 
 def _json_scalar_preview(value) -> str:
+    """Chuỗi xem trước ngắn cho một giá trị JSON, để nhãn node không quá dài."""
     if isinstance(value, dict):
         return f"{{…}} ({len(value)} keys)"
     if isinstance(value, list):
@@ -262,6 +280,11 @@ def _json_scalar_preview(value) -> str:
 
 
 def _add_json_value(graph: StructureGraph, parent_id: str, fp: str, value, depth: int) -> None:
+    """Thêm cấu trúc một giá trị JSON vào đồ thị, chặn ở ``MAX_JSON_DEPTH``.
+
+    Có trần độ sâu vì JSON lồng sâu sẽ sinh ra hàng nghìn node mà chẳng nói lên
+    điều gì về cấu trúc dự án.
+    """
     if depth >= MAX_JSON_DEPTH:
         return
     if isinstance(value, dict):
@@ -325,6 +348,9 @@ def build_from_codebase_memory(mem, repo_path, mode: str = "all",
 
 
 def _iter_results(res):
+    """Duyệt kết quả trả về từ bộ nhớ mã nguồn, chấp nhận nhiều khuôn khoá khác nhau
+    (``results`` / ``nodes`` / ``items`` / ``data``).
+    """
     if isinstance(res, dict):
         for key in ("results", "nodes", "items", "data"):
             val = res.get(key)
@@ -339,6 +365,10 @@ def _iter_results(res):
 # Layout (layered by distance from roots)
 # --------------------------------------------------------------------------
 def layered_layout(graph: StructureGraph, col_w: int = 280, row_h: int = 64) -> Tuple[Dict[str, Tuple[int, int]], Dict[str, int]]:
+    """Xếp đồ thị thành các cột theo bậc phụ thuộc, trong cột xếp dọc.
+
+    Trả về (toạ độ từng node, lớp của từng node).
+    """
     indeg = {n.id: 0 for n in graph.nodes}
     adj = defaultdict(list)
     for e in graph.edges:
diff --git a/core/task_excel.py b/core/task_excel.py
index 9da0030..8845efe 100644
--- a/core/task_excel.py
+++ b/core/task_excel.py
@@ -42,10 +42,12 @@ _TRUE = {"yes", "y", "true", "1", "x", "có", "co"}
 
 
 def _bool(value) -> bool:
+    """Đọc giá trị đúng/sai từ ô Excel, chấp nhận nhiều cách ghi."""
     return str(value or "").strip().lower() in _TRUE
 
 
 def _clamp(value, allowed, default):
+    """Ép một giá trị về tập hợp lệ; ngoài tập thì lấy mặc định."""
     v = str(value or "").strip().lower()
     return v if v in allowed else default
 
diff --git a/core/task_executors.py b/core/task_executors.py
index 2faf485..57de9a9 100644
--- a/core/task_executors.py
+++ b/core/task_executors.py
@@ -38,16 +38,21 @@ CancelFn = Callable[[], bool]
 
 
 def new_run_id() -> str:
+    """Id lượt chạy mới: mốc thời gian cộng 6 ký tự ngẫu nhiên (chống trùng khi hai
+    task khởi động cùng giây).
+    """
     return datetime.now().strftime("%Y%m%d-%H%M%S-") + uuid.uuid4().hex[:6]
 
 
 def artifact_dir(task_id: str, run_id: str) -> Path:
+    """Thư mục hiện vật của một lượt chạy, tạo sẵn cả thư mục con ``generated_files``."""
     d = ARTIFACTS_DIR / task_id / run_id
     (d / "generated_files").mkdir(parents=True, exist_ok=True)
     return d
 
 
 def _last_assistant_text(messages) -> str:
+    """Nội dung trả lời cuối cùng của assistant trong hội thoại; '' nếu không có."""
     for m in reversed(messages or []):
         if m.get("role") == "assistant" and (m.get("content") or "").strip():
             return m["content"]
@@ -64,6 +69,7 @@ _OUTPUT_MODE_HINTS = {
 
 
 def _output_mode_hint(task: Dict[str, Any]) -> str:
+    """Câu hướng dẫn định dạng đầu ra tương ứng chế độ output của task."""
     return _OUTPUT_MODE_HINTS.get(task.get("output", {}).get("output_mode", "text"), "")
 
 
@@ -104,6 +110,9 @@ def _project_folder_input_text(project: Optional[projects.Project], max_files: i
 def _build_prompt(task: Dict[str, Any], tasks_dir: Path = None,
                   project: Optional[projects.Project] = None,
                   max_files: int = 10) -> str:
+    """Ghép prompt cho một task: mô tả, dữ liệu vào đã phân giải, chỉ dẫn chung của
+    project, và gợi ý định dạng đầu ra.
+    """
     parts = [task.get("description") or task.get("title") or ""]
     extra = resolve_input_text(task, tasks_dir)
     if extra:
@@ -202,6 +211,7 @@ def _cancel_with_timeout(cancel: CancelFn, timeout_sec: Optional[int]) -> Tuple[
     state = {"timed_out": False}
 
     def wrapped() -> bool:
+        """Cờ huỷ có thêm hạn giờ: người dùng bấm Dừng HOẶC quá thời gian cho phép."""
         if cancel():
             return True
         if time.monotonic() >= deadline:
@@ -280,6 +290,7 @@ def _run_agent(ctx, task_type: str, prompt: str, out_dir: Path,
     last_plan_steps: List[Dict[str, str]] = []
 
     def emit_and_autosave(ev):
+        """Chuyển tiếp sự kiện tiến độ và tự lưu hội thoại tại các mốc an toàn."""
         emit(ev)
         if not isinstance(ev, dict):
             return
@@ -348,6 +359,7 @@ def _run_agent(ctx, task_type: str, prompt: str, out_dir: Path,
 
 
 def _run_script(command: str, out_dir: Path, timeout_sec: int) -> str:
+    """Chạy một task kiểu script bằng shell trong thư mục kết quả, có hạn giờ."""
     if not command.strip():
         raise RuntimeError("Script task has no command configured.")
     proc = subprocess.run(command, shell=True, cwd=str(out_dir),
@@ -456,6 +468,7 @@ def _run_co4e_flow(ctx, task: Dict[str, Any], wf, gen_dir: Path,
     outputs: Dict[str, str] = {}
 
     def _emit(ev):
+        """Chuyển tiếp sự kiện của luồng Co4E về dạng sự kiện task."""
         if not isinstance(ev, dict):
             return
         t = ev.get("type")
diff --git a/core/task_import.py b/core/task_import.py
index da540d3..3d2bc48 100644
--- a/core/task_import.py
+++ b/core/task_import.py
@@ -73,6 +73,7 @@ def auto_chain_in_order(tasks: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
 
 # ---- CSV -----------------------------------------------------------------
 def _import_csv(path: Path) -> List[Dict[str, Any]]:
+    """Đọc danh sách task từ file CSV (chấp nhận BOM của Excel)."""
     try:
         text = path.read_text(encoding="utf-8-sig")
     except OSError as exc:
@@ -111,6 +112,7 @@ def _import_csv(path: Path) -> List[Dict[str, Any]]:
 
 # ---- JSON ----------------------------------------------------------------
 def _import_json(path: Path) -> List[Dict[str, Any]]:
+    """Đọc danh sách task từ file JSON."""
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, json.JSONDecodeError) as exc:
@@ -138,6 +140,11 @@ def _import_json(path: Path) -> List[Dict[str, Any]]:
 
 
 def _pick(d: Dict[str, Any], *keys, default=""):
+    """Lấy giá trị đầu tiên khác rỗng trong các khoá được nêu.
+
+    File nhập từ nhiều nguồn đặt tên cột khác nhau (``title``/``name``/``Tiêu đề``),
+    nên phải thử lần lượt.
+    """
     for k in keys:
         if k in d and d[k] not in (None, ""):
             return d[k]
@@ -145,6 +152,7 @@ def _pick(d: Dict[str, Any], *keys, default=""):
 
 
 def _clamp(value, allowed, default):
+    """Ép một giá trị về tập hợp lệ; ngoài tập thì lấy mặc định."""
     v = str(value or "").strip().lower()
     return v if v in allowed else default
 
@@ -213,6 +221,7 @@ _TRUE = {"yes", "y", "true", "1", "x", "có", "co"}
 
 
 def _truthy(value) -> bool:
+    """Đọc giá trị đúng/sai từ nhiều kiểu ghi khác nhau (bool, 'yes', '1', 'có'…)."""
     if isinstance(value, bool):
         return value
     return str(value or "").strip().lower() in _TRUE
diff --git a/core/task_scheduler.py b/core/task_scheduler.py
index 2a7d3ce..27832ab 100644
--- a/core/task_scheduler.py
+++ b/core/task_scheduler.py
@@ -31,6 +31,13 @@ STOP_WAIT_SECS = 10.0
 
 
 class TaskScheduler(QObject):
+    """Bộ chạy task theo lịch: cứ mỗi nhịp lại tìm task tới hạn và chạy chúng ở
+    luồng nền.
+
+    Đồng hồ được tiêm qua ``clock=`` (R07-T03) nên test chạy được mà không cần
+    ``QTimer`` thật, và các checker UI vô hiệu hoá được nó để việc dựng cửa sổ
+    không vô tình chạy task thật của người dùng.
+    """
     tasks_changed = Signal()           # any status/log change → UI refresh
     task_started = Signal(str)         # task_id
     task_finished = Signal(str, bool)  # task_id, ok
@@ -40,6 +47,9 @@ class TaskScheduler(QObject):
     history_ready = Signal(str)        # task_id
 
     def __init__(self, ctx, tasks_dir: Optional[Path] = None, parent=None, clock=None):
+        """``clock`` để None thì tự dựng ``QtSchedulerClock`` thật, nên mọi chỗ gọi cũ
+        không phải sửa; test tiêm ``FakeClock`` để điều khiển nhịp bằng tay.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self.tasks_dir = tasks_dir            # None → default TASKS_DIR
@@ -48,7 +58,7 @@ class TaskScheduler(QObject):
         self._session_ids: Dict[str, str] = {}       # task_id → its run's History session id
         # R07-T03: the QTimer this class used to own directly is now behind a
         # small clock interface (start/stop/pump) — see
-        # platform/qt/qt_scheduler_clock.py::QtSchedulerClock. Defaulting to a
+        # infrastructure/qt/qt_scheduler_clock.py::QtSchedulerClock. Defaulting to a
         # real one here keeps every existing production call site (which
         # never passes `clock=`) unchanged; tests inject
         # tests/fakes/fake_clock.py::FakeClock to control ticks by hand with
@@ -62,6 +72,9 @@ class TaskScheduler(QObject):
 
     # ---- lifecycle ----------------------------------------------------
     def start(self) -> None:
+        """Bắt đầu chạy: thu dọn task còn kẹt từ lần chạy trước, đuổi kịp task đã quá
+        hạn, rồi bật nhịp đếm.
+        """
         self._recover_orphans()
         self.tick()          # catch up overdue tasks right at app start
         self._clock.start(TICK_MS, self.tick)
@@ -111,6 +124,7 @@ class TaskScheduler(QObject):
 
     # ---- tick / dispatch ----------------------------------------------
     def tick(self) -> None:
+        """Một nhịp: chạy mọi task đã tới hạn tại thời điểm này."""
         now = datetime.now()
         changed = False
         for task in due_tasks(list_tasks(self.tasks_dir), now):
@@ -147,6 +161,7 @@ class TaskScheduler(QObject):
         return True
 
     def is_running(self, task_id: str) -> bool:
+        """Task này có đang chạy không."""
         return task_id in self._workers
 
     def running_count(self) -> int:
@@ -163,6 +178,7 @@ class TaskScheduler(QObject):
 
     # ---- internals -----------------------------------------------------
     def _start(self, task: dict) -> None:
+        """Khởi động một task ở luồng nền và đánh dấu trạng thái 'running'."""
         tid = task["task_id"]
         run_id = new_run_id()
         task["status"] = "running"
@@ -170,6 +186,7 @@ class TaskScheduler(QObject):
         self.task_started.emit(tid)
 
         def job(worker: AgentWorker):
+            """Chạy nền: thực thi task, chuyển tiếp sự kiện tiến độ và cờ huỷ."""
             return execute_task(self.ctx, task, run_id,
                                 emit=worker.emit_event, cancel=worker.is_cancelled,
                                 tasks_dir=self.tasks_dir)
@@ -197,6 +214,7 @@ class TaskScheduler(QObject):
         self.history_ready.emit(task_id)
 
     def _on_done(self, task_id: str, run_id: str, result: dict) -> None:
+        """Task chạy xong: ghi kết quả, tính lần chạy kế tiếp, và kích hoạt task nối tiếp."""
         self._workers.pop(task_id, None)
         self._session_ids.pop(task_id, None)
         task = load_task(task_id, self.tasks_dir)
@@ -249,6 +267,11 @@ class TaskScheduler(QObject):
             self._start(task)
 
     def _apply_chain(self, task: dict, verb: str, next_id: str) -> None:
+        """Kích hoạt task nối tiếp theo luật ``run_next``.
+
+        Task kế đang tạm dừng thì BỎ QUA — trình sửa task có cảnh báo trước về
+        điều này.
+        """
         nxt = load_task(next_id, self.tasks_dir)
         if not nxt or nxt.get("status") == "paused":
             return   # paused next task is skipped (warned about in the editor)
@@ -265,6 +288,11 @@ class TaskScheduler(QObject):
         save_task(nxt, self.tasks_dir)
 
     def _notify(self, task: dict, ok: bool, error: str) -> None:
+        """Gửi nhắc việc qua Teams hoặc Outlook khi task kết thúc.
+
+        Đã chọn kênh thì báo cả khi chạy xong LẪN khi lỗi — im lặng lúc lỗi là
+        kiểu hỏng tệ nhất của một tác vụ chạy nền.
+        """
         ex = task["execution"]
         channel = ex.get("notify_channel", "none")
         # A chosen channel notifies on BOTH completion and error; the legacy
diff --git a/core/tasks.py b/core/tasks.py
index cff3f44..f03a757 100644
--- a/core/tasks.py
+++ b/core/tasks.py
@@ -98,10 +98,12 @@ DEFAULT_TASK: Dict[str, Any] = {
 
 
 def _now_str() -> str:
+    """Mốc thời gian hiện tại theo đúng định dạng lưu trong file task."""
     return datetime.now().strftime(_TIME_FMT)
 
 
 def parse_run_at(value: Optional[str]) -> Optional[datetime]:
+    """Đọc chuỗi thời gian chạy thành ``datetime``; sai định dạng thì trả ``None``."""
     if not value:
         return None
     try:
@@ -111,6 +113,7 @@ def parse_run_at(value: Optional[str]) -> Optional[datetime]:
 
 
 def format_run_at(dt: datetime) -> str:
+    """Ghi ``datetime`` thành chuỗi thời gian chạy."""
     return dt.strftime(_TIME_FMT)
 
 
@@ -143,10 +146,12 @@ def _normalize(task: Dict[str, Any]) -> Dict[str, Any]:
 
 # ---- repository ----------------------------------------------------------
 def task_path(task_id: str, directory: Path = None) -> Path:
+    """Đường dẫn file JSON của một task."""
     return (directory or TASKS_DIR) / f"{task_id}.json"
 
 
 def save_task(task: Dict[str, Any], directory: Path = None) -> Path:
+    """Ghi task xuống đĩa (ghi nguyên tử) và cập nhật ``updated_at``."""
     directory = directory or TASKS_DIR
     directory.mkdir(parents=True, exist_ok=True)
     task["updated_at"] = datetime.now().isoformat(timespec="seconds")
@@ -163,6 +168,7 @@ def save_task(task: Dict[str, Any], directory: Path = None) -> Path:
 
 
 def load_task(task_id: str, directory: Path = None) -> Optional[Dict[str, Any]]:
+    """Đọc một task theo id và chuẩn hoá; không có hoặc hỏng thì trả ``None``."""
     path = task_path(task_id, directory)
     try:
         return _normalize(json.loads(path.read_text(encoding="utf-8")))
@@ -171,6 +177,7 @@ def load_task(task_id: str, directory: Path = None) -> Optional[Dict[str, Any]]:
 
 
 def list_tasks(directory: Path = None) -> List[Dict[str, Any]]:
+    """Liệt kê mọi task trong thư mục; thư mục chưa có thì trả list rỗng."""
     directory = directory or TASKS_DIR
     if not directory.exists():
         return []
@@ -185,6 +192,7 @@ def list_tasks(directory: Path = None) -> List[Dict[str, Any]]:
 
 
 def delete_task(task_id: str, directory: Path = None) -> None:
+    """Xoá file task; không có thì bỏ qua."""
     try:
         task_path(task_id, directory).unlink()
     except OSError:
@@ -306,6 +314,11 @@ _calculator: Optional[Any] = None
 
 
 def _get_calculator():
+    """Bộ tính lịch (:class:`ScheduleCalculator`), dựng một lần rồi dùng lại.
+
+    Dựng lười để ``core/tasks.py`` không kéo theo cả module cron ở mỗi lần
+    import.
+    """
     global _calculator
     if _calculator is None:
         from .cron import Cron
diff --git a/core/teams.py b/core/teams.py
index e7bc1c5..fd3fe92 100644
--- a/core/teams.py
+++ b/core/teams.py
@@ -17,12 +17,21 @@ ACCENT = "F37021"
 
 
 class TeamsNotifier:
+    """Gửi thông báo lên Microsoft Teams qua webhook.
+
+    Tự thử hai khuôn thẻ: Adaptive Card (webhook Workflows mới) rồi tới
+    MessageCard (webhook Connector cũ) — hai loại webhook không nhận chung một khuôn.
+    """
     def __init__(self, webhook_url: str = "", ca_bundle: str = ""):
+        """``webhook_url`` rỗng nghĩa là chưa cấu hình — mọi lượt gửi về sau lặng lẽ bỏ
+        qua thay vì lỗi.
+        """
         self.webhook_url = (webhook_url or "").strip()
         self.ca_bundle = (ca_bundle or "").strip()
 
     @property
     def configured(self) -> bool:
+        """Đã cấu hình webhook hợp lệ chưa."""
         return self.webhook_url.startswith("http")
 
     def send(
@@ -113,6 +122,7 @@ class TeamsNotifier:
 
     @staticmethod
     def _explain(resp) -> str:
+        """Đổi phản hồi lỗi của Teams thành câu đọc được, kèm mã HTTP và 200 ký tự thân."""
         code = resp.status_code
         body = (getattr(resp, "text", "") or "")[:200]
         if code == 405:
@@ -127,6 +137,7 @@ class TeamsNotifier:
 
     @staticmethod
     def _message_card(title: str, text: str, facts: Optional[Dict[str, str]]) -> Dict:
+        """Dựng payload khuôn MessageCard (webhook Connector cũ)."""
         section: Dict = {"activityTitle": title, "text": text}
         if facts:
             section["facts"] = [{"name": k, "value": v} for k, v in facts.items()]
@@ -140,6 +151,7 @@ class TeamsNotifier:
 
     @staticmethod
     def _adaptive_card(title: str, text: str, facts: Optional[Dict[str, str]]) -> Dict:
+        """Dựng payload khuôn Adaptive Card (webhook Workflows mới)."""
         body: List[Dict] = [
             {"type": "TextBlock", "text": title, "weight": "Bolder", "size": "Medium"},
             {"type": "TextBlock", "text": text, "wrap": True},
diff --git a/core/telemetry_shared.py b/core/telemetry_shared.py
index 6eb2ff7..a541da7 100644
--- a/core/telemetry_shared.py
+++ b/core/telemetry_shared.py
@@ -19,6 +19,11 @@ from typing import Any, Dict, List, Optional
 
 def _load_events(shared_dir: str, subdir: str, start: Optional[date],
                  end: Optional[date]) -> List[Dict[str, Any]]:
+    """Đọc sự kiện telemetry từ thư mục chia sẻ của đội, lọc theo khoảng ngày.
+
+    Thư mục chưa có thì trả list rỗng — máy chưa đồng bộ xong không được làm vỡ
+    màn Giám sát.
+    """
     directory = Path(shared_dir).expanduser() / "telemetry" / subdir
     if not directory.exists():
         return []
diff --git a/core/tls_trust.py b/core/tls_trust.py
index 61edd3c..65965cb 100644
--- a/core/tls_trust.py
+++ b/core/tls_trust.py
@@ -53,15 +53,22 @@ def looks_like_cert_trust_error(exc: BaseException) -> bool:
 
 
 def _host_port(url: str) -> tuple[str, int]:
+    """Cặp (host, port) rút từ URL; không có port thì mặc định 443."""
     parsed = urlparse(url)
     return parsed.hostname or "", parsed.port or 443
 
 
 def _slug(host: str) -> str:
+    """Tên file an toàn suy từ host."""
     return re.sub(r"[^a-zA-Z0-9.-]", "_", host) or "host"
 
 
 def trusted_cert_path(url: str) -> Path:
+    """Đường dẫn file PEM ghim chứng chỉ cho một host.
+
+    Mỗi host một file: gateway nội bộ dùng chứng chỉ tự ký, ghim đúng chứng chỉ
+    đã thấy lần đầu (trust on first use) thay vì tắt kiểm chứng chỉ.
+    """
     host, _port = _host_port(url)
     return TRUST_DIR / f"{_slug(host)}.pem"
 
diff --git a/core/tools.py b/core/tools.py
index e6e2fda..ee3faf9 100644
--- a/core/tools.py
+++ b/core/tools.py
@@ -188,6 +188,7 @@ def combine_tool_sources(*sources):
         return [], None
 
     def combined_executor(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Định tuyến một lời gọi tool về đúng nguồn của nó (dựng sẵn, MCP hay connector)."""
         executor = routing.get(name)
         if executor is None:
             return {"ok": False, "output": f"Unknown tool: {name}"}
@@ -286,6 +287,9 @@ def execute_tool(ctx: ToolContext, name: str, args: Dict[str, Any],
 
 
 def _short_json(obj: Any, limit: int = 500) -> str:
+    """Chuỗi JSON đã cắt ngắn để đưa vào log hoặc bong bóng chat, tránh nhấn chìm
+    màn hình bằng một kết quả dài.
+    """
     import json
     text = json.dumps(obj, ensure_ascii=False, indent=2)
     return text if len(text) <= limit else text[:limit] + " …"
diff --git a/core/usage_cost.py b/core/usage_cost.py
index ae86b30..bd1487d 100644
--- a/core/usage_cost.py
+++ b/core/usage_cost.py
@@ -36,6 +36,7 @@ _CURRENCY_FMT = {"USD": ("$", 4), "VND": ("₫", 0), "JPY": ("¥", 1)}
 SUPPORTED_CURRENCIES = tuple(_CURRENCY_FMT)
 
 def cost_usd(summary: Dict[str, Any], pricing: Dict[str, Any]) -> Dict[str, float]:
+    """Quy số token thành tiền (USD) theo bảng đơn giá, tách riêng vào/ra/cache."""
     p = {**DEFAULT_PRICING, **(pricing or {})}
     return {
         "in": summary.get("in", 0) / 1e6 * float(p["price_per_mtok_in_usd"]),
diff --git a/core/usage_periods.py b/core/usage_periods.py
index 87e4540..99fc316 100644
--- a/core/usage_periods.py
+++ b/core/usage_periods.py
@@ -24,6 +24,7 @@ def bucketed_series(events: List[Dict[str, Any]], granularity: str = "day",
     pricing = pricing or {}
 
     def _key(ts: Any) -> str:
+        """Khoá gom nhóm của một mốc thời gian theo độ mịn (tuần/tháng/năm)."""
         s = str(ts or "")[:10]
         if granularity == "year":
             return s[:4]
@@ -65,6 +66,7 @@ def period_bounds(gran: str, offset: int, today: Optional[date] = None) -> tuple
     return date(y, m + 1, 1), date(y2, m2 + 1, 1)
 
 def _period_label(gran: str, start: date) -> str:
+    """Nhãn hiển thị của một kỳ: thứ Hai đầu tuần, YYYY-MM, hoặc năm."""
     if gran == "week":
         return start.isoformat()          # the week's Monday (YYYY-MM-DD)
     if gran == "year":
@@ -73,6 +75,7 @@ def _period_label(gran: str, start: date) -> str:
 
 def _sum_between(events: List[Dict[str, Any]], start: date, end: date,
                  pricing: Dict[str, Any]) -> tuple:
+    """Tổng token và chi phí của các sự kiện trong khoảng ``[start, end)``."""
     lo, hi = start.isoformat(), end.isoformat()
     evs = [e for e in events if lo <= str(e.get("ts", ""))[:10] < hi]
     tokens = sum(int(e.get("in", 0) or 0) + int(e.get("out", 0) or 0)
diff --git a/core/usage_tracker.py b/core/usage_tracker.py
index 9b129ba..50579aa 100644
--- a/core/usage_tracker.py
+++ b/core/usage_tracker.py
@@ -103,6 +103,11 @@ def end_accumulation() -> None:
 
 
 def estimate_tokens(text: str) -> int:
+    """Ước lượng số token của một đoạn văn bản theo tỉ lệ 4 ký tự ≈ 1 token.
+
+    Ước lượng thô là đủ: con số này chỉ dùng để quyết định khi nào nén lịch sử,
+    không dùng để tính tiền (tiền lấy từ số token thật provider trả về).
+    """
     return max(0, len(text or "") // 4)
 
 
diff --git a/core/windows_sandbox_vm.py b/core/windows_sandbox_vm.py
index dbfb665..6f68972 100644
--- a/core/windows_sandbox_vm.py
+++ b/core/windows_sandbox_vm.py
@@ -158,6 +158,7 @@ class WindowsSandboxVM:
                     pass
 
     def _error(self, message: str) -> Dict[str, Any]:
+        """Kết quả lỗi theo đúng khuôn chung của bộ chạy sandbox."""
         return {
             "ok": False,
             "stdout": "",
diff --git a/core/worker.py b/core/worker.py
index 1b3746f..ce53ebf 100644
--- a/core/worker.py
+++ b/core/worker.py
@@ -18,12 +18,23 @@ Job = Callable[["AgentWorker"], Optional[Dict[str, Any]]]
 
 
 class AgentWorker(QThread):
+    """Luồng nền chạy một lượt agent, nối kết quả về giao diện qua signal Qt.
+
+    Mọi việc chậm (gọi model, chạy tool, trích tệp) đều phải nằm trong đây —
+    chạy ở luồng giao diện là cả cửa sổ đứng hình.
+    """
     event = Signal(dict)                 # streaming/agent events
     permission_requested = Signal(dict)  # confirm-mode tool action awaiting approval
     finished_ok = Signal(dict)           # job completed
     failed = Signal(str)                 # job raised
 
     def __init__(self, job: Job, parent=None):
+        """Bọc một hàm thành luồng nền.
+
+        ``stop_event`` để công khai vì provider cần truyền thẳng nó vào
+        ``Event.wait()`` — nhờ vậy bấm Dừng là dừng ngay, không phải đợi hết lượt
+        chờ mạng hiện tại.
+        """
         super().__init__(parent)
         self._job = job
         self.stop_event = threading.Event()  # public for provider Event.wait() — immediate Stop
@@ -31,12 +42,15 @@ class AgentWorker(QThread):
 
     # -- helpers used from inside the job (worker thread) --------------
     def is_cancelled(self) -> bool:
+        """``True`` khi người dùng đã bấm Dừng — job phải tự thoát sớm."""
         return self.stop_event.is_set()
 
     def emit_event(self, ev: Dict[str, Any]) -> None:
+        """Đẩy một sự kiện tiến độ về giao diện."""
         self.event.emit(ev)
 
     def new_gate(self, mode: str, agent_role: str = "") -> PermissionGate:
+        """Dựng cổng phê duyệt cho lượt này (chế độ hỏi trước khi chạy tool)."""
         self.gate = PermissionGate(
             mode, on_request=lambda action: self.permission_requested.emit(action),
             agent_role=agent_role,
@@ -45,16 +59,26 @@ class AgentWorker(QThread):
 
     # -- control from the UI thread -----------------------------------
     def request_stop(self) -> None:
+        """Yêu cầu dừng: bật cờ huỷ và giải phóng cổng phê duyệt đang chờ.
+
+        Phải huỷ cả cổng, nếu không job sẽ kẹt mãi ở chỗ chờ người dùng bấm Đồng ý.
+        """
         self.stop_event.set()
         if self.gate:
             self.gate.cancel()
 
     def resolve_permission(self, approved: bool) -> None:
+        """Trả lời một yêu cầu phê duyệt tool đang chờ."""
         if self.gate:
             self.gate.resolve(approved)
 
     # -- thread body ---------------------------------------------------
     def run(self) -> None:  # noqa: D401
+        """Thân luồng: chạy job rồi phát ``finished_ok``, lỗi thì phát ``failed``.
+
+        Bắt mọi ngoại lệ: một lỗi lọt ra khỏi đây sẽ giết luồng mà giao diện không
+        nhận được tín hiệu nào — người dùng thấy nút Dừng quay mãi.
+        """
         try:
             result = self._job(self)
             self.finished_ok.emit(result or {})
diff --git a/core/xlsx_write.py b/core/xlsx_write.py
index 1406944..cdbb33d 100644
--- a/core/xlsx_write.py
+++ b/core/xlsx_write.py
@@ -33,6 +33,7 @@ def _openpyxl():
 
 
 def is_available() -> bool:
+    """Máy đã cài ``openpyxl`` chưa — không có thì mọi tính năng Excel tắt."""
     return _openpyxl() is not None
 
 
diff --git a/domain/agents/agent_event.py b/domain/agents/agent_event.py
index 824ab88..3768797 100644
--- a/domain/agents/agent_event.py
+++ b/domain/agents/agent_event.py
@@ -55,6 +55,7 @@ class ToolPreview:
     text: str = ""
 
     def to_dict(self) -> Dict[str, str]:
+        """Ba khoá đúng như ``core/tools.py::describe_action`` trả về — không thêm không bớt."""
         return {"kind": self.kind, "title": self.title, "text": self.text}
 
     @classmethod
@@ -84,6 +85,7 @@ class PlanStep:
     status: str = "pending"
 
     def to_dict(self) -> Dict[str, str]:
+        """Một bước kế hoạch dưới dạng dict, để đưa vào payload sự kiện."""
         return {"title": self.title, "status": self.status}
 
 
@@ -129,6 +131,7 @@ class TextChunkEvent(AgentEvent):
     delta: str = ""
 
     def _payload(self) -> Dict[str, Any]:
+        """``{delta}`` — một mẩu câu trả lời đang phát dần."""
         return {"delta": self.delta}
 
 
@@ -140,6 +143,7 @@ class ReasoningChunkEvent(AgentEvent):
     delta: str = ""
 
     def _payload(self) -> Dict[str, Any]:
+        """``{delta}`` — một mẩu suy luận nội bộ của model."""
         return {"delta": self.delta}
 
 
@@ -156,6 +160,7 @@ class AssistantMessageCompletedEvent(AgentEvent):
     content: str = ""
 
     def _payload(self) -> Dict[str, Any]:
+        """``{content}`` — nội dung trọn vẹn của một lượt gọi provider."""
         return {"content": self.content}
 
 
@@ -178,6 +183,11 @@ class ToolCallStartedEvent(AgentEvent):
     preview: Optional[ToolPreview] = None
 
     def _payload(self) -> Dict[str, Any]:
+        """``{id, name, args}``, kèm ``preview`` chỉ khi thật sự có.
+
+        Không có xem trước thì BỎ HẲN khoá thay vì gửi ``None``: widget đang viết
+        ``ev.get("preview") or {}``, tức nó đã quen với việc khoá vắng mặt.
+        """
         payload: Dict[str, Any] = {"id": self.call_id, "name": self.name,
                                    "args": dict(self.arguments)}
         # Omitted rather than sent as None: the widget does
@@ -198,6 +208,7 @@ class ToolOutputChunkEvent(AgentEvent):
     delta: str = ""
 
     def _payload(self) -> Dict[str, Any]:
+        """``{id, name, delta}`` — một mẩu đầu ra tool đang chạy."""
         return {"id": self.call_id, "name": self.name, "delta": self.delta}
 
 
@@ -215,9 +226,19 @@ class ToolCallFinishedEvent(AgentEvent):
 
     def __post_init__(self) -> None:
         # Callers pass a live list; freeze it so the event cannot change later.
+        """Đóng băng danh sách tệp đầu ra thành tuple.
+
+        Bên gọi truyền vào một list đang sống; không sao chép thì sự kiện đã phát đi
+        vẫn đổi nội dung được về sau — sự kiện phải là ảnh chụp bất biến.
+        """
         object.__setattr__(self, "produced", _as_str_tuple(self.produced))
 
     def _payload(self) -> Dict[str, Any]:
+        """``{id, name, ok, output}``, kèm ``error``/``produced`` chỉ khi có.
+
+        Hai khoá sau vắng mặt khi rỗng, đúng như ``chat_agent`` vẫn phát: phía
+        nhận kiểm bằng ``ev.get(...)`` nên thêm giá trị rỗng là đổi hành vi.
+        """
         payload: Dict[str, Any] = {"id": self.call_id, "name": self.name,
                                    "ok": self.ok, "output": self.output}
         # Both keys stay ABSENT when empty, matching what chat_agent emits today:
@@ -241,9 +262,11 @@ class PlanUpdatedEvent(AgentEvent):
     steps: Tuple[PlanStep, ...] = ()
 
     def __post_init__(self) -> None:
+        """Đóng băng danh sách bước kế hoạch thành tuple."""
         object.__setattr__(self, "steps", tuple(self.steps or ()))
 
     def _payload(self) -> Dict[str, Any]:
+        """``{steps}`` — cả danh sách bước, vì agent gửi lại trọn kế hoạch mỗi lần cập nhật."""
         return {"steps": [s.to_dict() for s in self.steps]}
 
 
@@ -260,6 +283,7 @@ class NoticeEvent(AgentEvent):
     level: str = NOTICE_INFO
 
     def _payload(self) -> Dict[str, Any]:
+        """``{level, text}`` — một dòng thông báo (info / cảnh báo / tiến độ)."""
         return {"level": self.level, "text": self.text}
 
 
@@ -271,9 +295,11 @@ class OutputsAddedEvent(AgentEvent):
     paths: Tuple[str, ...] = ()
 
     def __post_init__(self) -> None:
+        """Đóng băng danh sách đường dẫn thành tuple."""
         object.__setattr__(self, "paths", _as_str_tuple(self.paths))
 
     def _payload(self) -> Dict[str, Any]:
+        """``{paths}`` — các tệp vừa sinh ra, đổi về list cho JSON hoá được."""
         return {"paths": list(self.paths)}
 
 
@@ -285,9 +311,11 @@ class OutputsRemovedEvent(AgentEvent):
     paths: Tuple[str, ...] = ()
 
     def __post_init__(self) -> None:
+        """Đóng băng danh sách đường dẫn thành tuple."""
         object.__setattr__(self, "paths", _as_str_tuple(self.paths))
 
     def _payload(self) -> Dict[str, Any]:
+        """``{paths}`` — các tệp trung gian vừa được dọn."""
         return {"paths": list(self.paths)}
 
 
@@ -303,6 +331,7 @@ class HistoryReadyEvent(AgentEvent):
     session_id: str = ""
 
     def _payload(self) -> Dict[str, Any]:
+        """``{session_id}`` — lịch sử đã ghi xong, kèm id phiên để mở lại."""
         return {"session_id": self.session_id}
 
 
@@ -327,6 +356,7 @@ class TurnCompletedEvent(AgentEvent):
     budget_exhausted: bool = False      # stopped at effective_max_steps
 
     def _payload(self) -> Dict[str, Any]:
+        """``{final_text, steps_used, cancelled, budget_exhausted}`` — tổng kết cả lượt."""
         return {"final_text": self.final_text, "steps_used": self.steps_used,
                 "cancelled": self.cancelled, "budget_exhausted": self.budget_exhausted}
 
@@ -345,6 +375,7 @@ class ErrorEvent(AgentEvent):
     recoverable: bool = False
 
     def _payload(self) -> Dict[str, Any]:
+        """``{message, recoverable}`` — lỗi kèm cờ có thể thử lại hay không."""
         return {"message": self.message, "recoverable": self.recoverable}
 
 
diff --git a/domain/agents/agent_event_codec.py b/domain/agents/agent_event_codec.py
index 4caf845..eb459bb 100644
--- a/domain/agents/agent_event_codec.py
+++ b/domain/agents/agent_event_codec.py
@@ -11,6 +11,16 @@ declares the vocabulary, the other bridges it to the old wire format.
 Serialisation the other way lives on the events themselves
 (``AgentEvent.to_legacy_dict``), because an event has to be emittable without
 anyone importing a codec.
+
+SEAM · dựng 2026-08-23 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``presentation/chat`` dùng thẳng sự kiện có kiểu, không còn đọc dict cũ nữa.
+Để dormant thì sao: Shim này để xoá, không để giữ. Còn nó thì khuôn dict cũ
+vẫn là một hợp đồng phải duy trì.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 
 from __future__ import annotations
diff --git a/domain/security/tool_policy.py b/domain/security/tool_policy.py
index f5d60f4..d46ae5d 100644
--- a/domain/security/tool_policy.py
+++ b/domain/security/tool_policy.py
@@ -20,6 +20,16 @@ Mô hình bám theo code đang chạy, không bịa:
 
 Điểm khác biệt duy nhất so với hôm nay: gộp hai thứ đó thành **một câu trả lời
 ba trạng thái**, thay vì code gọi phải tự nhớ hỏi cả hai nơi.
+
+SEAM · dựng 2026-08-21 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``application/conversations/tool_policy_gateway.py`` trả về ``PolicyDecision`` thay cho ``bool``.
+Để dormant thì sao: Hiện gateway chỉ trả đúng/sai nên lý do chặn bị mất —
+đúng thứ kiểu dữ liệu này sinh ra để mang theo.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
@@ -79,20 +89,28 @@ class PolicyDecision:
         return self.outcome is PolicyOutcome.ALLOW
 
     def __post_init__(self):
+        """Ép mọi quyết định DENY/ASK phải kèm lý do.
+
+        Người dùng thấy lý do trên hộp thoại, và nhật ký kiểm toán ghi lại nó — một
+        quyết định chặn không lý do là không truy được về sau.
+        """
         if self.outcome is not PolicyOutcome.ALLOW and not self.reason:
             raise ValueError("DENY và ASK bắt buộc có reason — người dùng và "
                              "audit log đều cần biết vì sao")
 
 
 def allow() -> PolicyDecision:
+    """Quyết định cho phép. Không cần lý do: đây là đường đi bình thường."""
     return PolicyDecision(PolicyOutcome.ALLOW)
 
 
 def deny(reason: str, layer: str = "policy") -> PolicyDecision:
+    """Quyết định chặn hẳn, kèm lý do và tên lớp đã ra quyết định."""
     return PolicyDecision(PolicyOutcome.DENY, reason, layer)
 
 
 def ask(reason: str, layer: str = "policy") -> PolicyDecision:
+    """Quyết định phải hỏi người dùng, kèm lý do và tên lớp đã ra quyết định."""
     return PolicyDecision(PolicyOutcome.ASK, reason, layer)
 
 
diff --git a/domain/tasks/schedule_calculator.py b/domain/tasks/schedule_calculator.py
index 20b49e8..d0b117c 100644
--- a/domain/tasks/schedule_calculator.py
+++ b/domain/tasks/schedule_calculator.py
@@ -41,10 +41,12 @@ class _CronLike(Protocol):
     ``core/cron.py::Cron`` without this module importing it."""
 
     def next_after(self, after: datetime) -> Optional[datetime]:
+        """Lần chạy kế tiếp sau một mốc thời gian; ``None`` nếu không bao giờ."""
         ...
 
 
 def _parse_run_at(value: Optional[str]) -> Optional[datetime]:
+    """Đọc chuỗi thời gian chạy thành ``datetime``; sai định dạng thì trả ``None``."""
     if not value:
         return None
     try:
@@ -69,6 +71,9 @@ class ScheduleCalculator:
     def __init__(self,
                 is_holiday: Optional[Callable[[Any, str], bool]] = None,
                 make_cron: Optional[Callable[[str], _CronLike]] = None) -> None:
+        """``is_holiday``/``make_cron`` tiêm được nên lớp này không phụ thuộc vào lịch
+        nghỉ hay bộ phân tích cron nào cụ thể — test truyền hàm giả vào.
+        """
         self._is_holiday = is_holiday
         self._make_cron = make_cron
 
diff --git a/domain/tools/tool_registry.py b/domain/tools/tool_registry.py
index 0cfceab..99db0c4 100644
--- a/domain/tools/tool_registry.py
+++ b/domain/tools/tool_registry.py
@@ -37,17 +37,23 @@ class ToolRegistry:
     """
 
     def __init__(self, descriptors: Optional[Iterable[ToolDescriptor]] = None) -> None:
+        """Đăng ký sẵn một loạt tool. Đi qua ``register`` chứ không gán thẳng dict để
+        mọi kiểm tra trùng tên đều chạy.
+        """
         self._by_name: Dict[str, ToolDescriptor] = {}
         for descriptor in descriptors or ():
             self.register(descriptor)
 
     def register(self, descriptor: ToolDescriptor) -> None:
+        """Đăng ký (hoặc thay thế) một tool theo tên."""
         self._by_name[descriptor.name] = descriptor
 
     def get(self, name: str) -> Optional[ToolDescriptor]:
+        """Mô tả của một tool; ``None`` nếu chưa đăng ký."""
         return self._by_name.get(name)
 
     def all(self) -> List[ToolDescriptor]:
+        """Danh sách mọi tool đã đăng ký."""
         return list(self._by_name.values())
 
     def specs(self) -> List[ToolSpec]:
@@ -67,9 +73,11 @@ class ToolRegistry:
         return descriptor.capabilities if descriptor is not None else ToolCapability.NONE
 
     def __contains__(self, name: str) -> bool:
+        """``"tên" in registry`` — tra theo tên tool."""
         return name in self._by_name
 
     def __len__(self) -> int:
+        """Số tool đã đăng ký."""
         return len(self._by_name)
 
 
diff --git a/domain/workflows/__init__.py b/domain/workflows/__init__.py
index e69de29..ebd3cb4 100644
--- a/domain/workflows/__init__.py
+++ b/domain/workflows/__init__.py
@@ -0,0 +1 @@
+"""Thực thể và DTO thuần Python của phân hệ luồng công việc (Co4E)."""
diff --git a/domain/workflows/run_record.py b/domain/workflows/run_record.py
index dcafbae..b0aec88 100644
--- a/domain/workflows/run_record.py
+++ b/domain/workflows/run_record.py
@@ -32,6 +32,16 @@ là hành vi đã được test khẳng định:
   * ``from_dict({})``/``from_dict(None)`` mặc định ``status`` là ``"done"``
     (không phải ``"running"``) — nên KHÔNG bị nhánh phía trên đổi thành
     "stopped".
+
+SEAM · dựng 2026-08-25 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``Co4EWorkflowService`` được nối dây — cùng điều kiện với seam ấy.
+Để dormant thì sao: DTO này và ``core/co4e_run_manager.py::RunHandle`` là
+hai bản của cùng một thứ; chỉ một bản được phép ở lại.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
@@ -50,6 +60,9 @@ class RunRecord:
     def __init__(self, run_id: str, wf_id: str, name: str, total: int,
                  plan_mode: bool, manual: bool, created_by: str = "", created_at: str = "",
                  project_id: str = ""):
+        """Dựng một bản ghi run. ``total`` âm bị kẹp về 0 — quirk cố ý giữ nguyên từ
+        ``Co4ERunManager`` cũ, xem docstring đầu file.
+        """
         self.id = run_id
         self.wf_id = wf_id
         self.name = name
@@ -68,9 +81,13 @@ class RunRecord:
 
     @property
     def running(self) -> bool:
+        """Run này còn đang chạy không."""
         return self.status == "running"
 
     def progress_text(self) -> str:
+        """Chuỗi tiến độ để hiện lên bảng: "3/7" khi biết tổng số bước, còn không thì
+        hiện trạng thái.
+        """
         return f"{self.done}/{self.total}" if self.total else self.status
 
     # ---- (de)serialization --------------------------------------------
@@ -93,6 +110,11 @@ class RunRecord:
 
     @classmethod
     def from_dict(cls, rec: dict) -> "RunRecord":
+        """Dựng lại một run từ dict đọc ở file lịch sử.
+
+        Mọi trường đều có mặc định và được ép kiểu: file lịch sử là dữ liệu cũ có
+        thể thiếu trường mà bản mới đã thêm.
+        """
         rec = dict(rec or {})
         r = cls(str(rec.get("id", "")), str(rec.get("wf_id", "")),
                  rec.get("name", ""), int(rec.get("total", 0) or 0),
diff --git a/domain/workspaces/workspace_session.py b/domain/workspaces/workspace_session.py
index 4fbbda4..1b38187 100644
--- a/domain/workspaces/workspace_session.py
+++ b/domain/workspaces/workspace_session.py
@@ -53,6 +53,9 @@ class WorkspaceSession:
     allowed_paths: Tuple[Path, ...] = field(default_factory=tuple)
 
     def __post_init__(self) -> None:
+        """Không khai đường dẫn cho phép thì mặc định đúng một đường: thư mục gốc của
+        phiên. Để rỗng nghĩa là KHÔNG cho phép gì cả, không phải cho phép tất.
+        """
         if not self.allowed_paths:
             object.__setattr__(self, "allowed_paths", (self.workspace_root,))
 
diff --git a/i18n.py b/i18n.py
index 885ca2a..9f0267f 100644
--- a/i18n.py
+++ b/i18n.py
@@ -74,10 +74,17 @@ def set_language(lang: str) -> None:
 
 
 def get_language() -> str:
+    """Mã ngôn ngữ đang dùng."""
     return _current
 
 
 def tr(key: str, **kwargs) -> str:
+    """Chuỗi đã dịch cho một khoá.
+
+    Thiếu khoá thì trả về CHÍNH khoá đó — hiện ra một chuỗi lạ trên giao diện
+    vẫn tốt hơn là làm vỡ màn hình. Thiếu bản dịch của ngôn ngữ hiện tại thì rơi
+    về tiếng Anh.
+    """
     entry = STRINGS.get(key)
     if not entry:
         return key
diff --git a/infrastructure/config/config_repository.py b/infrastructure/config/config_repository.py
index 476c58e..588fcc5 100644
--- a/infrastructure/config/config_repository.py
+++ b/infrastructure/config/config_repository.py
@@ -12,6 +12,17 @@ thật, xếp theo số lần gọi.
 Một chỗ cố ý KHÔNG đưa vào: ``config.data`` (36 lần gọi, nhiều nhất). Đó là
 đống dict thô — cho nó vào interface là bê nguyên vấn đề cũ sang kiến trúc mới.
 Ai đang cần ``data`` thì mở issue để bổ sung một thuộc tính có kiểu rõ ràng.
+
+SEAM · dựng 2026-08-21 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: một chỗ chú thích kiểu thật sự nhận ``ConfigRepository`` thay vì ``AppConfig``.
+Để dormant thì sao: Protocol không ai chú thích tới thì không có bộ kiểm
+kiểu nào đối chiếu nó với ``JsonConfigRepository``, nên hai bên lệch nhau
+lúc nào không hay.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
@@ -30,6 +41,7 @@ class ConfigRepository(Protocol):
         ...
 
     def set_active_provider(self, name: str) -> None:
+        """Đổi provider đang dùng."""
         ...
 
     def provider_conf(self, name: str | None = None) -> Dict[str, Any]:
@@ -62,6 +74,7 @@ class ConfigRepository(Protocol):
         ...
 
     def set_theme(self, value: str) -> None:
+        """Đổi giao diện sáng/tối."""
         ...
 
     @property
@@ -70,6 +83,7 @@ class ConfigRepository(Protocol):
         ...
 
     def set_language(self, value: str) -> None:
+        """Đổi ngôn ngữ hiển thị."""
         ...
 
     # ---- các nhóm cấu hình còn lại -------------------------------------
@@ -94,6 +108,7 @@ class ConfigRepository(Protocol):
         ...
 
     def set_tool_enabled(self, name: str, enabled: bool) -> None:
+        """Bật/tắt một tool theo tên."""
         ...
 
     # ---- ghi ------------------------------------------------------------
diff --git a/infrastructure/config/config_sections.py b/infrastructure/config/config_sections.py
new file mode 100644
index 0000000..4a7949b
--- /dev/null
+++ b/infrastructure/config/config_sections.py
@@ -0,0 +1,128 @@
+"""Các nhóm cấu hình đọc thẳng từ dict — tách khỏi ``json_config_repository.py``.
+
+Mỗi thành viên ở đây chỉ làm đúng một việc: đặt tên cho một khoá trong file
+cấu hình và nói rõ giá trị mặc định khi khoá đó chưa có. Không có hành vi nào
+đáng bàn, nhưng có đến hơn hai mươi cái — để chung với phần có logic thật
+(trộn mặc định, kho bí mật, di trú schema, ghi nguyên tử) thì phần ấy bị chìm.
+
+Dùng ``setdefault`` chứ không ``get``: bên gọi sửa thẳng vào dict trả về
+(``cfg.routing["switch_mode"] = ...``) rồi mới ``save()``, nên cái trả về phải
+là dict THẬT nằm trong ``data``, không phải một bản sao rồi bị vứt đi.
+
+Mixin chứ không phải lớp riêng: 29 file đang gọi ``ctx.config.<tên>`` thẳng,
+nên tách thành ``ctx.config.sections.<tên>`` sẽ là đổi API công khai — việc
+này chỉ chia file, không chia bề mặt.
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict
+
+
+class ConfigSectionsMixin:
+    """Phần truy cập nhóm cấu hình của :class:`JsonConfigRepository`.
+
+    Chỉ trông vào hai thứ của lớp chủ: ``self.data`` (dict cấu hình đã trộn
+    mặc định) và ``self.save()``. Không tự đứng một mình được — và cũng không
+    cần, vì không có ai khác dùng.
+    """
+
+
+    @property
+    def code(self) -> Dict[str, Any]:
+        """Nhóm ``code``: thiết lập của agent lập trình (thư mục làm việc, model)."""
+        return self.data["code"]
+
+    @property
+    def teams(self) -> Dict[str, Any]:
+        """Nhóm ``teams``: thiết lập tích hợp Microsoft Teams."""
+        return self.data["teams"]
+
+    @property
+    def history(self) -> Dict[str, Any]:
+        """Nhóm ``history``: lưu lịch sử hội thoại (bật/tắt, giới hạn)."""
+        return self.data["history"]
+
+    @property
+    def codebase_memory(self) -> Dict[str, Any]:
+        """Nhóm ``codebase_memory``: bộ nhớ mã nguồn cho agent lập trình."""
+        return self.data["codebase_memory"]
+
+    @property
+    def cowork(self) -> Dict[str, Any]:
+        """Nhóm ``cowork``: thiết lập màn Cowork (thư mục kết quả, model mặc định)."""
+        return self.data["cowork"]
+
+    @property
+    def mcp_servers(self) -> list:
+        """Danh sách máy chủ MCP đã khai báo; rỗng nếu chưa có cái nào."""
+        return self.data.setdefault("mcp_servers", [])
+
+    @property
+    def structure(self) -> Dict[str, Any]:
+        """Nhóm ``structure``: trần số node/cạnh khi vẽ đồ thị GraphRAG.
+
+        Mặc định 400/400 — vượt ngưỡng đó thì đồ thị vừa vẽ chậm vừa rối, không
+        còn đọc được nữa.
+        """
+        return self.data.setdefault("structure", {"max_nodes": 400, "max_edges": 400})
+
+    @property
+    def monitoring_visibility(self) -> Dict[str, bool]:
+        """Nhóm ``monitoring_visibility``: tab nào của màn Giám sát được hiện.
+
+        Lấy bản sao sâu của mặc định khi khoá chưa có, để người dùng tắt một tab
+        không vô tình sửa luôn bộ mặc định dùng chung.
+        """
+        return self.data.setdefault(
+            "monitoring_visibility",
+            copy.deepcopy(self._defaults["monitoring_visibility"]))
+
+    @property
+    def ext_connectors(self) -> Dict[str, list]:
+        """Connector (MCP) gom theo nhóm CAD/CAE/MS365/Other."""
+        d = self.data.setdefault(
+            "ext_connectors", {"cad": [], "cae": [], "ms365": [], "other": []})
+        for cat in ("cad", "cae", "ms365", "other"):
+            d.setdefault(cat, [])
+        return d
+
+    # ---- công tắc tổng cho connector -------------------------------------
+
+    @property
+    def connect_external(self) -> bool:
+        """Tắt cái này là agent không nối tới connector ngoài nào cả. Mặc định
+        BẬT để cấu hình đang chạy không đổi hành vi."""
+        return bool(self.data.setdefault("tools", {}).get("connect_external", True))
+
+    def set_connect_external(self, enabled: bool) -> None:
+        """Bật/tắt công tắc tổng cho connector ngoài, ghi đĩa ngay."""
+        self.data.setdefault("tools", {})["connect_external"] = bool(enabled)
+        self.save()
+
+    # ---- những thứ đã gieo sẵn -------------------------------------------
+
+    @property
+    def seeded_library_skills(self) -> list:
+        """Slug của skill thư viện đã gieo — để cái người dùng xoá đi không bị
+        lặng lẽ gieo lại."""
+        return list(self.data.setdefault("seeded_library_skills", []))
+
+    @seeded_library_skills.setter
+    def seeded_library_skills(self, slugs) -> None:
+        """Ghi lại danh sách slug đã gieo, bỏ trùng và giữ nguyên thứ tự."""
+        self.data["seeded_library_skills"] = list(dict.fromkeys(slugs or []))
+
+    @property
+    def seeded_builtin_flows(self) -> list:
+        """Id của flow Co4E dựng sẵn đã gieo (cùng quy tắc tôn trọng việc người
+        dùng đã xoá như seeded_library_skills)."""
+        return list(self.data.setdefault("seeded_builtin_flows", []))
+
+    @seeded_builtin_flows.setter
+    def seeded_builtin_flows(self, ids) -> None:
+        """Ghi lại danh sách id flow đã gieo, bỏ trùng và giữ nguyên thứ tự."""
+        self.data["seeded_builtin_flows"] = list(dict.fromkeys(ids or []))
+
+
+__all__ = ["ConfigSectionsMixin"]
diff --git a/infrastructure/config/json_config_repository.py b/infrastructure/config/json_config_repository.py
index 7d526e4..87f183a 100644
--- a/infrastructure/config/json_config_repository.py
+++ b/infrastructure/config/json_config_repository.py
@@ -22,20 +22,33 @@ from typing import Any, Dict
 
 from ..persistence.json.atomic_json_file import AtomicJsonFile
 from ..secrets.secret_store import SecretStore, provider_key
+from .config_sections import ConfigSectionsMixin
 from .schema_migration import CURRENT_VERSION, migrate
 
 
-class JsonConfigRepository:
+class JsonConfigRepository(ConfigSectionsMixin):
     """Cấu hình đọc/ghi từ một file JSON, bí mật để trong ``SecretStore``.
 
     ``secrets`` để None nghĩa là không có kho bí mật — mọi thứ vẫn chạy, chỉ
     là ``api_key`` lấy nguyên từ file như trước. Cần vậy để chuyển dần
     (R02-T05) chứ không phải đổi một phát cả app.
+
+    Các nhóm cấu hình đọc thẳng từ dict (``code``, ``teams``, ``history``,
+    connector, những thứ đã gieo sẵn…) nằm ở
+    ``config_sections.py::ConfigSectionsMixin``: chúng không có logic nào
+    riêng, chỉ đặt tên cho một khoá và một giá trị mặc định, nên để chung chỉ
+    làm trôi mất phần thật sự có hành vi của lớp này.
     """
 
     def __init__(self, path: Path, *, secrets: SecretStore | None = None,
                  defaults: Dict[str, Any] | None = None,
                  env_overrides=None):
+        """Mở một file cấu hình.
+
+        ``defaults``/``env_overrides`` để None thì lấy thẳng từ ``config.py`` — hai
+        bên phải dùng chung một bộ mặc định trong suốt giai đoạn chuyển, nếu không
+        ứng dụng sẽ thấy hai bộ cấu hình khác nhau tuỳ đường nào gọi tới.
+        """
         self._file = AtomicJsonFile(path)
         self._secrets = secrets
         # Lấy thẳng từ config.py để hai bên không lệch nhau trong lúc chuyển.
@@ -66,6 +79,7 @@ class JsonConfigRepository:
 
     # ---- nạp ------------------------------------------------------------
     def _load(self) -> Dict[str, Any]:
+        """Đọc file JSON, nâng cấp schema rồi trộn lên trên bộ mặc định."""
         merged = copy.deepcopy(self._defaults)
         stored = self._file.read(default=None)
         if isinstance(stored, dict):
@@ -84,11 +98,13 @@ class JsonConfigRepository:
         return merged
 
     def reload(self) -> None:
+        """Đọc lại toàn bộ cấu hình từ đĩa, bỏ mọi sửa đổi chưa ``save()``."""
         self.data = self._load()
 
     # ---- provider --------------------------------------------------------
     @property
     def active_provider(self) -> str:
+        """Id provider đang chọn ('openai_compat', 'anthropic', ...); '' nếu chưa đặt."""
         return self.data.get("active_provider", "")
 
     @active_provider.setter
@@ -100,6 +116,9 @@ class JsonConfigRepository:
         self.data["active_provider"] = name
 
     def set_active_provider(self, name: str) -> None:
+        """Đổi provider đang dùng. Bản hàm của property cùng tên, cho chỗ gọi thích
+        gọi hàm hơn gán thuộc tính.
+        """
         self.data["active_provider"] = name
 
     def provider_conf(self, name: str | None = None) -> Dict[str, Any]:
@@ -132,9 +151,13 @@ class JsonConfigRepository:
     # ---- đường dẫn -------------------------------------------------------
     @property
     def shared_dir(self) -> str:
+        """Thư mục dùng chung (OneDrive/mạng) chứa tài khoản và agent quản trị; '' là
+        chưa cấu hình.
+        """
         return self.data.get("shared_dir", "")
 
     def history_dir(self) -> Path:
+        """Thư mục chứa lịch sử hội thoại."""
         rt = getattr(self, "_project_history_dir", None) or self.data.get("_project_history_dir")
         if rt:
             return Path(rt)
@@ -145,6 +168,7 @@ class JsonConfigRepository:
         return CONFIG_DIR / "history"
 
     def cowork_output_dir(self) -> Path:
+        """Thư mục agent ghi kết quả ra."""
         custom = (self.data.get("cowork", {}).get("output_dir") or "").strip()
         if custom:
             return Path(custom).expanduser()
@@ -158,44 +182,64 @@ class JsonConfigRepository:
     # ---- giao diện -------------------------------------------------------
     @property
     def theme(self) -> str:
+        """Giao diện đang chọn: 'dark' | 'light' | 'system'. Mặc định 'dark'."""
         return self.data.get("theme", "dark")
 
     @theme.setter
     def theme(self, value: str) -> None:
+        """Đổi giao diện. Chỉ ghi vào bộ nhớ — phải ``save()`` mới xuống đĩa."""
         self.data["theme"] = value
 
     def set_theme(self, value: str) -> None:
+        """Đổi giao diện sáng/tối. Bản hàm của property ``theme``."""
         self.data["theme"] = value
 
     @property
     def language(self) -> str:
+        """Mã ngôn ngữ đang chọn: 'vi' | 'en' | 'ja'. Mặc định 'vi'."""
         return self.data.get("language", "vi")
 
     @language.setter
     def language(self, value: str) -> None:
+        """Đổi ngôn ngữ. Chỉ ghi vào bộ nhớ — phải ``save()`` mới xuống đĩa."""
         self.data["language"] = value
 
     def set_language(self, value: str) -> None:
+        """Đổi ngôn ngữ. Bản hàm của property ``language``."""
         self.data["language"] = value
 
     # ---- nhóm cấu hình ---------------------------------------------------
     @property
     def routing(self) -> Dict[str, Any]:
+        """Nhóm ``routing``: chế độ tự chọn model và các thiết lập riêng theo bề mặt chat."""
         return self.data.setdefault("routing", {})
 
     @property
     def auth(self) -> Dict[str, Any]:
+        """Nhóm ``auth``: thiết lập đăng nhập. Bản này không có lớp đăng nhập nên
+        thường rỗng.
+        """
         return self.data.setdefault("auth", {})
 
     @property
     def agent_security(self) -> Dict[str, Any]:
+        """Nhóm ``agent_security``: ngưỡng rủi ro và các mục agent phải xin phép."""
         return self.data.setdefault("agent_security", {})
 
     @property
     def tools_disabled(self) -> list[str]:
+        """Danh sách tool BỊ TẮT.
+
+        Lưu theo chiều "bị tắt" chứ không phải "được bật": tool mới thêm vào bản
+        cập nhật sẽ tự chạy được mà không cần ai vào bật thủ công.
+
+        Trả về BẢN SAO — sửa danh sách phải đi qua ``set_tool_enabled`` để còn ghi
+        đĩa.
+        """
         return list(self.data.get("tools_disabled", []))
 
     def set_tool_enabled(self, name: str, enabled: bool) -> None:
+        """Bật/tắt một tool. Lưu dưới dạng danh sách tool BỊ TẮT nên tool mới"""
         disabled = list(self.data.get("tools_disabled", []))
         if enabled:
             disabled = [t for t in disabled if t != name]
@@ -225,6 +269,7 @@ class JsonConfigRepository:
 
     @property
     def path(self) -> Path:
+        """Đường dẫn file config.json đang dùng."""
         return self._file.path
 
     # ---- TLS -------------------------------------------------------------
@@ -238,12 +283,14 @@ class JsonConfigRepository:
 
     @ca_bundle.setter
     def ca_bundle(self, value: str) -> None:
+        """Đặt file PEM riêng; chuỗi rỗng nghĩa là quay về kiểm chứng chỉ mặc định."""
         self.data["tls_ca_bundle"] = (value or "").strip()
 
     # ---- MS365 -----------------------------------------------------------
 
     @property
     def ms365(self) -> Dict[str, Any]:
+        """Nhóm ``ms365``: thiết lập Microsoft 365 kèm mã mở khoá phía giao diện."""
         return self.data.setdefault("ms365", copy.deepcopy(self._defaults["ms365"]))
 
     def ms365_try_unlock(self, code: str) -> bool:
@@ -257,87 +304,9 @@ class JsonConfigRepository:
         return False
 
     def ms365_lock(self) -> None:
+        """Khoá lại nhóm MS365 trong Cài đặt. Trạng thái khoá chỉ tồn tại lúc chạy."""
         self.data.setdefault("ms365", {})["unlocked"] = False
 
-    # ---- nhóm cấu hình đọc thẳng ------------------------------------------
-
-    @property
-    def code(self) -> Dict[str, Any]:
-        return self.data["code"]
-
-    @property
-    def teams(self) -> Dict[str, Any]:
-        return self.data["teams"]
-
-    @property
-    def history(self) -> Dict[str, Any]:
-        return self.data["history"]
-
-    @property
-    def codebase_memory(self) -> Dict[str, Any]:
-        return self.data["codebase_memory"]
-
-    @property
-    def cowork(self) -> Dict[str, Any]:
-        return self.data["cowork"]
-
-    @property
-    def mcp_servers(self) -> list:
-        return self.data.setdefault("mcp_servers", [])
-
-    @property
-    def structure(self) -> Dict[str, Any]:
-        return self.data.setdefault("structure", {"max_nodes": 400, "max_edges": 400})
-
-    @property
-    def monitoring_visibility(self) -> Dict[str, bool]:
-        return self.data.setdefault(
-            "monitoring_visibility",
-            copy.deepcopy(self._defaults["monitoring_visibility"]))
-
-    @property
-    def ext_connectors(self) -> Dict[str, list]:
-        """Connector (MCP) gom theo nhóm CAD/CAE/MS365/Other."""
-        d = self.data.setdefault(
-            "ext_connectors", {"cad": [], "cae": [], "ms365": [], "other": []})
-        for cat in ("cad", "cae", "ms365", "other"):
-            d.setdefault(cat, [])
-        return d
-
-    # ---- công tắc tổng cho connector -------------------------------------
-
-    @property
-    def connect_external(self) -> bool:
-        """Tắt cái này là agent không nối tới connector ngoài nào cả. Mặc định
-        BẬT để cấu hình đang chạy không đổi hành vi."""
-        return bool(self.data.setdefault("tools", {}).get("connect_external", True))
-
-    def set_connect_external(self, enabled: bool) -> None:
-        self.data.setdefault("tools", {})["connect_external"] = bool(enabled)
-        self.save()
-
-    # ---- những thứ đã gieo sẵn -------------------------------------------
-
-    @property
-    def seeded_library_skills(self) -> list:
-        """Slug của skill thư viện đã gieo — để cái người dùng xoá đi không bị
-        lặng lẽ gieo lại."""
-        return list(self.data.setdefault("seeded_library_skills", []))
-
-    @seeded_library_skills.setter
-    def seeded_library_skills(self, slugs) -> None:
-        self.data["seeded_library_skills"] = list(dict.fromkeys(slugs or []))
-
-    @property
-    def seeded_builtin_flows(self) -> list:
-        """Id của flow Co4E dựng sẵn đã gieo (cùng quy tắc tôn trọng việc người
-        dùng đã xoá như seeded_library_skills)."""
-        return list(self.data.setdefault("seeded_builtin_flows", []))
-
-    @seeded_builtin_flows.setter
-    def seeded_builtin_flows(self, ids) -> None:
-        self.data["seeded_builtin_flows"] = list(dict.fromkeys(ids or []))
-
     # ---- định tuyến theo từng bề mặt chat --------------------------------
 
     def routing_mode_for(self, surface: str) -> str:
@@ -352,6 +321,7 @@ class JsonConfigRepository:
         return mode if mode in self.ROUTING_MODES else "off"
 
     def set_routing_mode_for(self, surface: str, mode: str) -> None:
+        """Đặt chế độ định tuyến riêng cho một bề mặt chat, ghi đĩa ngay."""
         mode = mode if mode in self.ROUTING_MODES else "off"
         self.routing.setdefault("surface_modes", {})[surface] = mode
         self.save()
@@ -359,6 +329,7 @@ class JsonConfigRepository:
     # ---- tiện ích --------------------------------------------------------
 
     def model_label(self) -> str:
+        """Tên model đang dùng, để hiện trên thanh trạng thái; '?' nếu chưa đặt."""
         return str(self.provider_conf().get("model", "?"))
 
     # ---- ghi -------------------------------------------------------------
diff --git a/infrastructure/config/schema_migration.py b/infrastructure/config/schema_migration.py
index 1c53127..f562672 100644
--- a/infrastructure/config/schema_migration.py
+++ b/infrastructure/config/schema_migration.py
@@ -38,6 +38,11 @@ ASSUMED_VERSION = 1
 
 
 def read_version(data: Dict[str, Any]) -> int:
+    """Phiên bản schema của một dict cấu hình.
+
+    File cũ chưa có trường này thì coi như ``ASSUMED_VERSION`` — đó chính là
+    phiên bản trước khi trường được thêm vào.
+    """
     try:
         return int(data.get("schema_version", ASSUMED_VERSION))
     except (TypeError, ValueError):
diff --git a/infrastructure/config/settings_facade.py b/infrastructure/config/settings_facade.py
index 86f3ae8..3509f49 100644
--- a/infrastructure/config/settings_facade.py
+++ b/infrastructure/config/settings_facade.py
@@ -12,6 +12,16 @@ chứ không phải mili giây.
 Cố ý KHÔNG dùng dataclass đông cứng: đây là *khung nhìn* lên dict cấu hình
 sống, sửa qua đây là sửa vào dict rồi ``save()`` là xuống đĩa. Sao chép thành
 dataclass thì lại sinh chuyện đồng bộ hai chiều.
+
+SEAM · dựng 2026-08-22 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ít nhất một trong 156 lời gọi ``ctx.config.*`` chuyển sang đọc qua ``Settings``.
+Để dormant thì sao: Mục đích của nó là chặn lỗi gõ sai tên khoá. Không ai
+dùng thì không chặn được gì cả.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
@@ -22,9 +32,15 @@ class _View:
     """Khung nhìn lên một nhánh của dict cấu hình."""
 
     def __init__(self, data: Dict[str, Any]):
+        """Bọc một nhánh dict cấu hình để đọc bằng thuộc tính thay vì tra khoá."""
         self._d = data
 
     def _get(self, key: str, default: Any) -> Any:
+        """Đọc một khoá, coi ``None`` như thiếu.
+
+        Cấu hình cũ có chỗ ghi ``null``; nếu trả thẳng ``None`` ra ngoài thì
+        ``str(None)`` thành chuỗi "None" và lỗi hiện ra ở tận nơi dùng.
+        """
         value = self._d.get(key, default)
         return default if value is None else value
 
@@ -46,14 +62,17 @@ class ProviderSettings(_View):
 
     @property
     def base_url(self) -> str:
+        """Endpoint của provider. '' nghĩa là chưa cấu hình."""
         return str(self._get("base_url", ""))
 
     @property
     def model(self) -> str:
+        """Model mặc định của provider này. '' nghĩa là chưa chọn."""
         return str(self._get("model", ""))
 
     @property
     def api_key(self) -> str:
+        """Khoá API — đã được ``provider_conf()`` ghép từ kho bí mật của hệ điều hành."""
         return str(self._get("api_key", ""))
 
     @property
@@ -76,10 +95,12 @@ class RoutingSettings(_View):
 
     @switch_mode.setter
     def switch_mode(self, value: str) -> None:
+        """Đặt chế độ định tuyến chung. Sửa thẳng vào dict cấu hình sống."""
         self._d["switch_mode"] = value
 
     @property
     def enabled(self) -> bool:
+        """Định tuyến tự động có đang bật không (tức ``switch_mode`` khác "off")."""
         return self.switch_mode != "off"
 
     @property
@@ -99,18 +120,22 @@ class RoutingSettings(_View):
 
     @property
     def reassess_interval_hours(self) -> int:
+        """GIỜ giữa hai lần chấm điểm lại danh mục model."""
         return int(self._get("reassess_interval_hours", 24))
 
     @property
     def per_provider_concurrency(self) -> int:
+        """Số lượt gọi chạy song song tối đa cho mỗi provider khi dò/chấm điểm."""
         return int(self._get("per_provider_concurrency", 2))
 
     @property
     def judge_provider(self) -> str:
+        """Provider dùng làm trọng tài chấm điểm model. '' nghĩa là dùng provider đang chọn."""
         return str(self._get("judge_provider", ""))
 
     @property
     def judge_model(self) -> str:
+        """Model dùng làm trọng tài chấm điểm. '' nghĩa là dùng model mặc định của trọng tài."""
         return str(self._get("judge_model", ""))
 
 
@@ -119,22 +144,27 @@ class SecuritySettings(_View):
 
     @property
     def enabled(self) -> bool:
+        """Công tắc tổng của lớp an toàn. Tắt là bỏ qua mọi bước kiểm dưới đây."""
         return bool(self._get("enabled", True))
 
     @property
     def validate_prompt(self) -> bool:
+        """Có quét prompt người dùng tìm dấu hiệu tấn công tiêm lệnh không."""
         return bool(self._get("validate_prompt", True))
 
     @property
     def validate_attachments(self) -> bool:
+        """Có kiểm tệp đính kèm (đuôi/kiểu MIME nguy hiểm) trước khi đưa vào lượt chat không."""
         return bool(self._get("validate_attachments", True))
 
     @property
     def validate_commands(self) -> bool:
+        """Có phân loại rủi ro lệnh shell trước khi chạy không."""
         return bool(self._get("validate_commands", True))
 
     @property
     def command_ai_check(self) -> bool:
+        """Có nhờ thêm AI xét lệnh khi bộ luật tĩnh chưa chắc chắn không. Mặc định tắt vì tốn một lượt gọi."""
         return bool(self._get("command_ai_check", False))
 
     @property
@@ -148,10 +178,12 @@ class SecuritySettings(_View):
 
     @property
     def rules_onedrive_url(self) -> str:
+        """Link OneDrive tới bộ luật an toàn dùng chung. '' nghĩa là dùng bản đóng gói sẵn trong app."""
         return str(self._get("rules_onedrive_url", ""))
 
     @property
     def admin_email(self) -> str:
+        """Email quản trị nhận cảnh báo vi phạm. '' nghĩa là không gửi."""
         return str(self._get("admin_email", ""))
 
 
@@ -164,15 +196,21 @@ class Settings:
     """
 
     def __init__(self, repo):
+        """Bọc một ``ConfigRepository`` — mọi lượt đọc/ghi đều đi xuống nó, lớp này chỉ
+        đổi cách gọi cho dễ đọc.
+        """
         self._repo = repo
 
     def provider(self, name: str | None = None) -> ProviderSettings:
+        """Khung nhìn cấu hình của một provider; bỏ trống thì lấy provider đang chọn."""
         return ProviderSettings(self._repo.provider_conf(name))
 
     @property
     def routing(self) -> RoutingSettings:
+        """Khung nhìn nhóm cấu hình định tuyến model."""
         return RoutingSettings(self._repo.routing)
 
     @property
     def security(self) -> SecuritySettings:
+        """Khung nhìn nhóm cấu hình an toàn cho agent."""
         return SecuritySettings(self._repo.agent_security)
diff --git a/infrastructure/filesystem/command_tools.py b/infrastructure/filesystem/command_tools.py
index 0e8f763..c5e13c4 100644
--- a/infrastructure/filesystem/command_tools.py
+++ b/infrastructure/filesystem/command_tools.py
@@ -55,6 +55,11 @@ def _sandbox_python(ctx: ToolContext, cancel: Optional[CancelFn] = None,
 def run_command(ctx: ToolContext, args: Dict[str, Any],
                  cancel: Optional[CancelFn] = None,
                  on_output=None) -> Dict[str, Any]:
+    """Chạy một lệnh shell trong thư mục làm việc, có hạn giờ và có sandbox.
+
+    Biến môi trường được lọc và mạng bị chặn theo cấu hình an toàn — agent chạy
+    lệnh không được thừa hưởng toàn bộ môi trường của người dùng.
+    """
     from cowork_local.core.deps import network_blocked_env, run_cancellable, sandbox_env
     from cowork_local.core.sandbox_manager import ExecutionConfig, SandboxManager
     from cowork_local.security.command_risk_classifier import classify_command
@@ -96,6 +101,11 @@ def run_command(ctx: ToolContext, args: Dict[str, Any],
 def install_package(ctx: ToolContext, args: Dict[str, Any],
                      cancel: Optional[CancelFn] = None,
                      on_output=None) -> Dict[str, Any]:
+    """Cài một gói Python vào môi trường phụ trợ của lượt chạy.
+
+    Cài vào venv riêng chứ không vào Python của hệ thống — một task không được
+    phép làm hỏng môi trường của cả máy.
+    """
     from cowork_local.core.deps import pip_install
 
     package = str(args.get("package", "")).strip()
diff --git a/infrastructure/filesystem/execution_workspace.py b/infrastructure/filesystem/execution_workspace.py
index b907621..06b79fb 100644
--- a/infrastructure/filesystem/execution_workspace.py
+++ b/infrastructure/filesystem/execution_workspace.py
@@ -14,6 +14,17 @@ exactly what it always was. It exists so a caller (an application service,
 R06-T05's ``FileWorkspaceService``, or a future turn-cleanup step) can ask
 for "the output dir" / "the scratch dir" instead of hand-building the path
 and hoping the convention hasn't drifted.
+
+SEAM · dựng 2026-08-21 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: một chỗ gọi thật hỏi ``output_dir``/``scratch_dir`` thay vì tự ghép ``workdir / ".scratch"``.
+Để dormant thì sao: Quy ước ``.scratch`` vẫn nằm rải trong ``file_tools.py``
+và ``core/chat_agent.py``. File này đặt tên cho nó nhưng chưa ai dùng, nên
+quy ước vẫn trôi được.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
@@ -51,10 +62,12 @@ class ExecutionWorkspace:
 
     @property
     def output_dir(self) -> Path:
+        """Thư mục agent được phép ghi kết quả — chính là gốc của phiên làm việc."""
         return self.session.workspace_root
 
     @property
     def scratch_dir(self) -> Path:
+        """Thư mục nháp bên trong phiên, cho file tạm không phải kết quả cuối."""
         return self.session.workspace_root / SCRATCH_DIRNAME
 
     def ensure_dirs(self) -> None:
diff --git a/infrastructure/filesystem/fetch_tools.py b/infrastructure/filesystem/fetch_tools.py
index 5a5c98b..7e3f73d 100644
--- a/infrastructure/filesystem/fetch_tools.py
+++ b/infrastructure/filesystem/fetch_tools.py
@@ -36,6 +36,7 @@ def fetch_url(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def jira_search(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Tìm issue trên Jira bằng JQL."""
     from cowork_local.core import jira_tool
 
     out = jira_tool.search(ctx.jira, str(args.get("jql", "")),
@@ -45,6 +46,7 @@ def jira_search(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def jira_get_issue(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Lấy chi tiết một issue Jira theo mã."""
     from cowork_local.core import jira_tool
 
     out = jira_tool.get_issue(ctx.jira, str(args.get("key", "")))
diff --git a/infrastructure/filesystem/file_tools.py b/infrastructure/filesystem/file_tools.py
index b5b6a38..10cc91d 100644
--- a/infrastructure/filesystem/file_tools.py
+++ b/infrastructure/filesystem/file_tools.py
@@ -52,6 +52,10 @@ def _check_python_syntax(target: Path, content: str) -> str:
 
 
 def read_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Đọc một tệp trong thư mục làm việc, cắt ở ``MAX_READ_BYTES``.
+
+    Đường dẫn được ``ctx.resolve`` kiểm trước — thoát ra ngoài thư mục là bị từ chối.
+    """
     target = ctx.resolve(str(args.get("path", "")))
     if not target.exists():
         return {"ok": False, "output": f"File not found: {args.get('path')}"}
@@ -61,6 +65,7 @@ def read_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def list_dir(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Liệt kê tệp và thư mục con tại một đường dẫn (mặc định là gốc thư mục làm việc)."""
     rel = str(args.get("path", ".") or ".")
     target = ctx.resolve(rel)
     # A missing/not-yet-created path is NOT a tool failure — report it as an
@@ -79,6 +84,11 @@ def list_dir(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def write_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Tạo mới hoặc ghi đè một tệp, tự tạo thư mục cha.
+
+    ``ctx.flatten_writes`` ép mọi tệp ghi thẳng vào gốc — dùng cho lượt chạy mà
+    cấu trúc thư mục do agent bịa ra không có ý nghĩa gì.
+    """
     rel = str(args.get("path", ""))
     if ctx.flatten_writes:
         rel = _flatten_rel(rel)
diff --git a/infrastructure/filesystem/tool_context.py b/infrastructure/filesystem/tool_context.py
index a5d0057..ad681d9 100644
--- a/infrastructure/filesystem/tool_context.py
+++ b/infrastructure/filesystem/tool_context.py
@@ -18,11 +18,17 @@ CancelFn = Callable[[], bool]
 
 
 class ToolError(Exception):
+    """Lỗi khi chạy một tool — thông điệp được đưa thẳng cho model đọc."""
     pass
 
 
 @dataclass
 class ToolContext:
+    """Bối cảnh một lượt chạy tool: thư mục làm việc và các quy tắc ghi.
+
+    ``flatten_writes`` ép mọi tệp ghi thẳng vào gốc — dùng cho Cowork, nơi cấu
+    trúc thư mục do model bịa ra không có ý nghĩa với người dùng.
+    """
     workdir: Path
     flatten_writes: bool = False  # Cowork: force every write into the workdir root
     sandbox: bool = False  # Code tab: isolate run_command/install_package into <workdir>/.venv
diff --git a/infrastructure/mcp/mcp_source_manager.py b/infrastructure/mcp/mcp_source_manager.py
index 2962675..84a6147 100644
--- a/infrastructure/mcp/mcp_source_manager.py
+++ b/infrastructure/mcp/mcp_source_manager.py
@@ -34,6 +34,11 @@ class McpToolSourceManager:
     """
 
     def __init__(self, connection_factory=McpServerConnection) -> None:
+        """``connection_factory`` tiêm được để test không phải chạy tiến trình con thật.
+
+        Có khoá riêng vì nhiều lượt chat song song cùng gọi tới đây: kiểm-rồi-tạo mà
+        không khoá sẽ dựng hai kết nối cho cùng một máy chủ.
+        """
         self._connections: Dict[str, McpServerConnection] = {}
         self._lock = threading.Lock()
         self._connection_factory = connection_factory
@@ -69,6 +74,7 @@ class McpToolSourceManager:
         return self._connections.get(name)
 
     def is_alive(self, name: str) -> bool:
+        """Kết nối tới một MCP server còn sống không."""
         connection = self._connections.get(name)
         return connection is not None and connection.is_alive()
 
diff --git a/infrastructure/persistence/json/atomic_json_file.py b/infrastructure/persistence/json/atomic_json_file.py
index d4727a0..5448d10 100644
--- a/infrastructure/persistence/json/atomic_json_file.py
+++ b/infrastructure/persistence/json/atomic_json_file.py
@@ -40,6 +40,9 @@ class AtomicJsonFile:
     """
 
     def __init__(self, path: Path, *, indent: int = 2):
+        """Trỏ vào một file JSON. ``indent`` giữ file còn đọc và so sánh được bằng mắt
+        trong git diff.
+        """
         self.path = Path(path)
         self.indent = indent
 
@@ -63,6 +66,10 @@ class AtomicJsonFile:
             return default
 
     def _quarantine(self) -> Path | None:
+        """Đổi tên file JSON hỏng thành ``.bad-<mốc thời gian>`` thay vì xoá.
+
+        Giữ lại để còn cứu dữ liệu, và để lần ghi sau bắt đầu từ file sạch.
+        """
         stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
         target = self.path.with_suffix(self.path.suffix + f".bad-{stamp}")
         try:
@@ -125,7 +132,9 @@ class AtomicJsonFile:
 
     # ---- tiện ích -------------------------------------------------------
     def exists(self) -> bool:
+        """File đã tồn tại trên đĩa chưa."""
         return self.path.exists()
 
     def __repr__(self) -> str:
+        """Biểu diễn ngắn kèm đường dẫn, cho log và thông báo lỗi."""
         return f"AtomicJsonFile({self.path})"
diff --git a/infrastructure/persistence/json/conversation_repository_impl.py b/infrastructure/persistence/json/conversation_repository_impl.py
index 3a7677c..f3858f8 100644
--- a/infrastructure/persistence/json/conversation_repository_impl.py
+++ b/infrastructure/persistence/json/conversation_repository_impl.py
@@ -22,6 +22,11 @@ class ConversationRepository:
     ``directory`` (defaults to the app's real ``HISTORY_DIR``)."""
 
     def __init__(self, directory: Optional[Path] = None) -> None:
+        """``directory`` để None thì dùng thư mục lịch sử mặc định.
+
+        Import muộn ngay trong thân hàm để nạp module này không kéo theo cả cây cấu
+        hình — test trỏ thẳng vào ``tmp_path``.
+        """
         if directory is not None:
             self._directory = Path(directory)
         else:
@@ -29,18 +34,28 @@ class ConversationRepository:
             self._directory = HISTORY_DIR
 
     def new_session_id(self) -> str:
+        """Sinh id phiên mới cho một cuộc hội thoại."""
         return new_session_id()
 
     def save(self, kind: str, session_id: str, messages: List[Dict[str, Any]], **kwargs) -> Path:
+        """Ghi hội thoại xuống đĩa (ghi nguyên tử) và trả về đường dẫn file."""
         return save_conversation(self._directory, kind, session_id, messages, **kwargs)
 
     def load(self, path: Path) -> Dict[str, Any]:
+        """Đọc một hội thoại từ đường dẫn file."""
         return load_conversation(path)
 
     def list(self, query: str = "", **kwargs) -> List[Dict[str, Any]]:
+        """Liệt kê hội thoại trong thư mục; ``query`` lọc theo tiêu đề và nội dung."""
         return list_conversations(self._directory, query=query)
 
     def _resolve_path(self, target: Any) -> Path:
+        """Đổi id phiên (hoặc đường dẫn) thành đường dẫn file thật.
+
+        Nhận cả ba dạng: Path sẵn, đường dẫn tuyệt đối, và id phiên trần —
+        id trần thì dò theo mẫu ``*__<id>.json`` vì tiền tố là loại hội thoại
+        (cowork/co4e/...) mà chỗ gọi không phải lúc nào cũng biết.
+        """
         if isinstance(target, Path):
             return target
         p = Path(str(target))
@@ -51,12 +66,15 @@ class ConversationRepository:
         return self._directory / f"cowork__{target}.json"
 
     def rename(self, target: Any, new_title: str) -> None:
+        """Đổi tiêu đề một hội thoại."""
         rename_conversation(self._resolve_path(target), new_title)
 
     def delete(self, target: Any) -> None:
+        """Xoá hẳn một hội thoại khỏi đĩa."""
         delete_conversation(self._resolve_path(target))
 
     def set_pinned(self, target: Any, pinned: bool) -> None:
+        """Ghim/bỏ ghim một hội thoại để nó nằm trên đầu danh sách lịch sử."""
         set_pinned(self._resolve_path(target), pinned)
 
 
diff --git a/infrastructure/persistence/json/task_repository_impl.py b/infrastructure/persistence/json/task_repository_impl.py
index 0149a57..e30875f 100644
--- a/infrastructure/persistence/json/task_repository_impl.py
+++ b/infrastructure/persistence/json/task_repository_impl.py
@@ -29,6 +29,11 @@ class TaskRepository:
     folder)."""
 
     def __init__(self, directory: Optional[Path] = None) -> None:
+        """``directory`` để None thì dùng thư mục task mặc định.
+
+        Hai đường import cho cùng một hằng số: gói có thể được nạp dưới tên đầy đủ
+        ``cowork_local`` hoặc dưới dạng tương đối tuỳ cách chạy.
+        """
         if directory is None:
             try:
                 from cowork_local.core.tasks import TASKS_DIR
@@ -39,6 +44,7 @@ class TaskRepository:
             self._directory = directory
 
     def list(self) -> List[Dict[str, Any]]:
+        """Liệt kê mọi task trong thư mục."""
         try:
             from cowork_local.core.tasks import list_tasks
         except ImportError:
@@ -46,6 +52,7 @@ class TaskRepository:
         return list_tasks(self._directory)
 
     def get(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """Đọc một task theo id; trả về ``None`` nếu không có."""
         try:
             from cowork_local.core.tasks import load_task
         except ImportError:
@@ -53,6 +60,7 @@ class TaskRepository:
         return load_task(task_id, self._directory)
 
     def save(self, task: Dict[str, Any]) -> Path:
+        """Ghi task xuống đĩa (ghi nguyên tử) và trả về đường dẫn file."""
         try:
             from cowork_local.core.tasks import save_task
         except ImportError:
@@ -60,6 +68,7 @@ class TaskRepository:
         return save_task(task, self._directory)
 
     def create(self, title: str = "", **overrides: Any) -> Dict[str, Any]:
+        """Tạo một task mới trong bộ nhớ theo mẫu mặc định; chưa ghi đĩa."""
         try:
             from cowork_local.core.tasks import new_task
         except ImportError:
@@ -67,6 +76,7 @@ class TaskRepository:
         return new_task(title, **overrides)
 
     def duplicate(self, task: Dict[str, Any]) -> Dict[str, Any]:
+        """Nhân bản một task (id mới, trạng thái và lịch sử chạy được đặt lại)."""
         try:
             from cowork_local.core.tasks import duplicate_task
         except ImportError:
@@ -74,6 +84,7 @@ class TaskRepository:
         return duplicate_task(task)
 
     def delete(self, task_id: str) -> None:
+        """Xoá hẳn một task khỏi đĩa."""
         try:
             from cowork_local.core.tasks import delete_task
         except ImportError:
diff --git a/infrastructure/persistence/json/workspace_repository_impl.py b/infrastructure/persistence/json/workspace_repository_impl.py
index 1a884d7..0a7eccb 100644
--- a/infrastructure/persistence/json/workspace_repository_impl.py
+++ b/infrastructure/persistence/json/workspace_repository_impl.py
@@ -16,6 +16,9 @@ class WorkspaceRepository:
     ``tmp_path`` so nothing touches the user's real config folder)."""
 
     def __init__(self, directory: Optional[Path] = None) -> None:
+        """``directory`` để None thì dùng thư mục dự án mặc định; import muộn để không
+        kéo cấu hình vào lúc nạp module.
+        """
         if directory is not None:
             self._directory = Path(directory)
         else:
@@ -23,25 +26,31 @@ class WorkspaceRepository:
             self._directory = PROJECTS_DIR
 
     def list(self) -> List["Project"]:
+        """Liệt kê mọi project trong thư mục."""
         from cowork_local.core.projects import list_projects
         return list_projects(self._directory)
 
     def get(self, project_id: str) -> Optional["Project"]:
+        """Đọc một project theo id; trả về ``None`` nếu không có."""
         from cowork_local.core.projects import load_project
         return load_project(project_id, self._directory)
 
     def save(self, project: "Project") -> None:
+        """Ghi project xuống đĩa (ghi nguyên tử)."""
         from cowork_local.core.projects import save_project
         save_project(project, self._directory)
 
     def create(self, name: str, **kwargs) -> "Project":
+        """Tạo project mới và ghi ngay xuống đĩa."""
         from cowork_local.core.projects import new_project
         return new_project(name, directory=self._directory, **kwargs)
 
     def new(self, name: str, **kwargs) -> "Project":
+        """Bí danh của :meth:`create` — giữ cho mã cũ gọi ``new()`` vẫn chạy."""
         return self.create(name, **kwargs)
 
     def delete(self, project_id: str) -> bool:
+        """Xoá project; trả về ``True`` nếu có project để xoá."""
         from cowork_local.core.projects import delete_project
         return delete_project(project_id, self._directory)
 
diff --git a/infrastructure/providers/provider_registry.py b/infrastructure/providers/provider_registry.py
index 65e5b10..99adf32 100644
--- a/infrastructure/providers/provider_registry.py
+++ b/infrastructure/providers/provider_registry.py
@@ -116,6 +116,12 @@ class ProviderRegistry:
     def __init__(self, descriptors: Optional[Iterable[ProviderDescriptor]] = None) -> None:
         # Keyed by canonical id; alias resolution walks the values so an alias
         # can never shadow a real provider id.
+        """Đăng ký sẵn một loạt provider.
+
+        Khoá theo id chuẩn, còn bí danh được dò khi tra: nhờ vậy một bí danh không
+        bao giờ che mất một id thật. Có khoá riêng vì sổ đăng ký bị đọc từ nhiều
+        luồng.
+        """
         self._by_id: Dict[str, ProviderDescriptor] = {}
         self._lock = threading.RLock()
         for descriptor in descriptors or ():
@@ -206,9 +212,13 @@ class ProviderRegistry:
             return sorted(self._by_id)
 
     def __contains__(self, provider_id: object) -> bool:
+        """``"tên" in registry`` — tính cả bí danh, và giá trị không phải chuỗi thì
+        trả về False thay vì ném lỗi.
+        """
         return isinstance(provider_id, str) and self.find(provider_id) is not None
 
     def __len__(self) -> int:
+        """Số provider đã đăng ký (không đếm bí danh)."""
         with self._lock:
             return len(self._by_id)
 
diff --git a/infrastructure/qt/qt_scheduler_clock.py b/infrastructure/qt/qt_scheduler_clock.py
index 5cbb4e7..e588510 100644
--- a/infrastructure/qt/qt_scheduler_clock.py
+++ b/infrastructure/qt/qt_scheduler_clock.py
@@ -40,11 +40,15 @@ class QtSchedulerClock:
         # Parented so the timer is torn down with its owner instead of
         # outliving it — the same lifetime QTimer(self) gave it inside
         # TaskScheduler before this extraction.
+        """Dựng ``QTimer`` gắn vào ``parent`` để nó bị dọn cùng chủ sở hữu, đúng vòng
+        đời nó vốn có khi còn nằm trong ``TaskScheduler``.
+        """
         self._timer = QTimer(parent)
         self._timer.timeout.connect(self._on_timeout)
         self._callback: Optional[Callable[[], None]] = None
 
     def _on_timeout(self) -> None:
+        """Mỗi nhịp ``QTimer``: gọi callback đã đăng ký."""
         if self._callback is not None:
             self._callback()
 
@@ -57,6 +61,7 @@ class QtSchedulerClock:
         self._timer.start()
 
     def stop(self) -> None:
+        """Dừng nhịp đếm."""
         self._timer.stop()
 
     def pump(self) -> None:
diff --git a/infrastructure/sandbox/sandbox_capabilities.py b/infrastructure/sandbox/sandbox_capabilities.py
index 92c9de2..75926b9 100644
--- a/infrastructure/sandbox/sandbox_capabilities.py
+++ b/infrastructure/sandbox/sandbox_capabilities.py
@@ -17,6 +17,16 @@ don't exist yet. Adding a real Linux/macOS backend later is a 1-line flip of
 ``implemented`` plus whatever backend module implements it; adding a whole
 new OS is a call to :func:`register_profile`, no changes to
 :class:`SandboxCapabilityMatrix` itself.
+
+SEAM · dựng 2026-08-25 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``core/sandbox_manager.py`` chọn backend bằng ma trận này thay cho chuỗi ``if`` theo hệ điều hành.
+Để dormant thì sao: Ma trận mô tả cả những backend CHƯA có bản cài. Không ai
+đọc thì nó lệch với thực tế lúc nào không biết.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations
 
@@ -58,6 +68,11 @@ def detect_os(platform_name: Optional[str] = None) -> str:
 
 @dataclass(frozen=True)
 class SandboxBackend:
+    """Một cơ chế cách ly cụ thể của hệ điều hành.
+
+    ``implemented`` phân biệt cái đã có bản cài thật với cái mới chỉ khai báo —
+    ma trận này mô tả cả những gì CHƯA làm, nên thiếu cờ đó thì nó nói dối.
+    """
     name: str
     isolation_level: str   # "none" | "resource_limits" | "restricted_token" | "namespace" | "seatbelt" | "full_vm"
     implemented: bool      # whether a real backend exists today, vs. a declared placeholder
@@ -65,6 +80,9 @@ class SandboxBackend:
 
 @dataclass(frozen=True)
 class OsSandboxProfile:
+    """Hồ sơ sandbox của một hệ điều hành: có những backend nào và mức rủi ro nào
+    thì ưu tiên backend nào.
+    """
     operating_system: str
     backends: Tuple[SandboxBackend, ...]
     # risk tier -> ordered list of preferred backend names (first available wins)
@@ -73,6 +91,7 @@ class OsSandboxProfile:
 
 def _profile(operating_system: str, backends: Tuple[SandboxBackend, ...],
             routing: Dict[str, Tuple[str, ...]]) -> OsSandboxProfile:
+    """Dựng một ``OsSandboxProfile`` — chỉ để bảng khai báo bên dưới đọc gọn hơn."""
     return OsSandboxProfile(operating_system=operating_system, backends=backends, routing=routing)
 
 
@@ -150,6 +169,11 @@ class SandboxCapabilityMatrix:
 
     def __init__(self, operating_system: Optional[str] = None,
                 allow_direct_fallback: bool = True) -> None:
+        """``operating_system`` để None thì tự dò hệ điều hành đang chạy.
+
+        Hệ không có hồ sơ rơi về hồ sơ "không biết": thà chạy ở mức bảo thủ còn hơn
+        coi như không có ràng buộc nào.
+        """
         self.operating_system = operating_system if operating_system is not None else detect_os()
         self._profile = _PROFILES.get(self.operating_system, _UNKNOWN_PROFILE)
         self.allow_direct_fallback = allow_direct_fallback
diff --git a/infrastructure/secrets/__init__.py b/infrastructure/secrets/__init__.py
index e69de29..183e0f7 100644
--- a/infrastructure/secrets/__init__.py
+++ b/infrastructure/secrets/__init__.py
@@ -0,0 +1,3 @@
+"""Kho bí mật: đọc/ghi khoá API qua keyring của hệ điều hành thay vì để trong
+file cấu hình (R02).
+"""
diff --git a/infrastructure/secrets/keyring_adapter.py b/infrastructure/secrets/keyring_adapter.py
index be058a0..f4a795f 100644
--- a/infrastructure/secrets/keyring_adapter.py
+++ b/infrastructure/secrets/keyring_adapter.py
@@ -28,6 +28,11 @@ class KeyringAdapter:
     """
 
     def __init__(self, service: str = SERVICE):
+        """Dò xem máy có kho khoá dùng được không.
+
+        Backend ``fail`` của keyring vẫn import trót lọt nhưng ném lỗi ở mọi lượt
+        gọi, nên phải nhận ra nó ngay tại đây và coi như không có kho khoá.
+        """
         self.service = service
         self._backend = None
         self._available = False
@@ -57,6 +62,7 @@ class KeyringAdapter:
 
     # ---- SecretStore ----------------------------------------------------
     def get(self, key: str) -> str | None:
+        """Đọc một bí mật; máy không có kho bí mật thì trả ``None``."""
         if not self._available:
             return None
         try:
@@ -66,6 +72,11 @@ class KeyringAdapter:
             return None
 
     def set(self, key: str, value: str) -> None:
+        """Lưu một bí mật; không có kho thì chỉ ghi cảnh báo, KHÔNG ném lỗi.
+
+        App phải chạy được trên máy thiếu keyring — lúc đó khoá nằm lại trong file
+        cấu hình như trước.
+        """
         if not self._available:
             log.warning("không lưu được %r: máy này không có kho bí mật", key)
             return
@@ -75,6 +86,7 @@ class KeyringAdapter:
             log.warning("lưu khoá %r thất bại: %s", key, exc)
 
     def delete(self, key: str) -> None:
+        """Xoá một bí mật khỏi kho; không có kho thì bỏ qua."""
         if not self._available:
             return
         try:
@@ -83,4 +95,5 @@ class KeyringAdapter:
             pass
 
     def has(self, key: str) -> bool:
+        """Kho có chứa bí mật này không."""
         return self.get(key) is not None
diff --git a/infrastructure/telemetry/audit_logger.py b/infrastructure/telemetry/audit_logger.py
index 4c371cb..fa114a1 100644
--- a/infrastructure/telemetry/audit_logger.py
+++ b/infrastructure/telemetry/audit_logger.py
@@ -47,6 +47,7 @@ class CanonicalAuditEvent:
     machine: str
 
     def to_dict(self) -> Dict[str, Any]:
+        """Bản ghi dưới dạng dict để ghi JSONL."""
         return {
             "ts": self.ts,
             "kind": self.kind,
@@ -77,6 +78,7 @@ class CanonicalAuditEvent:
 
 @dataclass
 class _Identity:
+    """Danh tính gắn vào mọi bản ghi: tài khoản, vai trò, máy và thư mục chia sẻ."""
     account: str = ""
     role: str = ""
     machine: str = ""
@@ -90,6 +92,9 @@ class CanonicalAuditLogger:
     class can be constructed/injected instead of relying on globals."""
 
     def __init__(self, audit_dir: Path):
+        """Danh tính (người dùng, máy) được lấy một lần lúc dựng: nó không đổi trong
+        một phiên, và mỗi dòng nhật ký đều cần tới.
+        """
         self.audit_dir = Path(audit_dir)
         self._identity = _Identity()
 
@@ -126,6 +131,11 @@ class CanonicalAuditLogger:
             pass
 
     def _write_shared(self, event: CanonicalAuditEvent, now: datetime) -> None:
+        """Ghi thêm một bản sao vào thư mục chia sẻ của đội, nếu có cấu hình.
+
+        Thiếu thư mục chia sẻ hoặc thiếu tên máy thì bỏ qua — bản ghi cục bộ vẫn có,
+        và một lỗi ghi mạng không được làm hỏng lượt chạy.
+        """
         identity = self._identity
         if not identity.shared_dir or not identity.machine:
             return
diff --git a/infrastructure/telemetry/usage_sink.py b/infrastructure/telemetry/usage_sink.py
index ef5d8c3..62079b8 100644
--- a/infrastructure/telemetry/usage_sink.py
+++ b/infrastructure/telemetry/usage_sink.py
@@ -98,6 +98,9 @@ class UsageTrackerSink:
     def __init__(self, recorder=None) -> None:
         # The recorder is injectable so a test can verify the forwarding
         # contract without importing the real tracker (and its config paths).
+        """``recorder`` tiêm được để test kiểm việc chuyển tiếp mà không phải nạp bộ
+        theo dõi thật (và cả đống đường dẫn cấu hình của nó).
+        """
         self._recorder = recorder
 
     def _resolve_recorder(self):
@@ -150,6 +153,7 @@ class InMemoryUsageSink:
     """Collects events in a list — the test double for usage assertions."""
 
     def __init__(self) -> None:
+        """Giữ sự kiện trong bộ nhớ cho test. Có khoá vì sự kiện đến từ nhiều luồng."""
         self.events: List[UsageEvent] = []
         self._lock = threading.Lock()
 
@@ -166,11 +170,13 @@ class InMemoryUsageSink:
             return list(self.events)
 
     def clear(self) -> None:
+        """Xoá sạch sự kiện đã ghi (dùng trong test)."""
         with self._lock:
             self.events.clear()
 
     @property
     def total_tokens(self) -> int:
+        """Tổng token của mọi sự kiện đã ghi."""
         return sum(e.total_tokens for e in self.snapshot())
 
 
@@ -184,10 +190,14 @@ class CompositeUsageSink:
     """
 
     def __init__(self, sinks=None) -> None:
+        """Gộp nhiều đích nhận sự kiện thành một. Dùng ``RLock`` vì một đích có thể gọi
+        ngược lại vào composite trong lúc đang phát.
+        """
         self._sinks: List[UsageEventSink] = list(sinks or ())
         self._lock = threading.RLock()
 
     def add(self, sink: UsageEventSink) -> None:
+        """Thêm một đích ghi vào nhóm."""
         with self._lock:
             self._sinks.append(sink)
 
@@ -199,10 +209,16 @@ class CompositeUsageSink:
                 self._sinks.remove(sink)
 
     def sinks(self) -> List[UsageEventSink]:
+        """Bản sao danh sách đích ghi hiện tại (an toàn khi duyệt)."""
         with self._lock:
             return list(self._sinks)
 
     def emit(self, event: UsageEvent) -> None:
+        """Đẩy sự kiện tới mọi đích.
+
+        Một đích lỗi không được làm hỏng các đích còn lại — ghi số liệu là việc phụ,
+        không được phép làm vỡ lượt chat đang chạy.
+        """
         for sink in self.sinks():
             try:
                 sink.emit(event)
diff --git a/mcp_servers/ms365_server.py b/mcp_servers/ms365_server.py
index 2cfabde..0a0e239 100644
--- a/mcp_servers/ms365_server.py
+++ b/mcp_servers/ms365_server.py
@@ -28,6 +28,11 @@ _PREFIX = "ms365_"
 
 
 def _strip(name: str) -> str:
+    """Bỏ tiền tố ``ms365_`` khỏi tên tool.
+
+    MCP đã gom tool theo tên máy chủ nên để tiền tố nữa thành thừa; bộ thực
+    thi cũ vẫn dispatch theo tên có tiền tố, nên gỡ lúc ra và gắn lại lúc vào.
+    """
     return name[len(_PREFIX):] if name.startswith(_PREFIX) else name
 
 
@@ -63,6 +68,7 @@ def _dispatch(name: str, args: Dict[str, Any]) -> str:
 
 
 def build_server():
+    """Dựng máy chủ MCP cho nhóm tool MS365 và đăng ký hai handler của giao thức."""
     import mcp.types as types
     from mcp.server.lowlevel import Server
 
@@ -70,22 +76,26 @@ def build_server():
 
     @app.list_tools()
     async def list_tools() -> List["types.Tool"]:
+        """Trả về danh sách tool MS365 hiện có, đọc từ cấu hình mới nhất."""
         return [types.Tool(**t) for t in _tool_list()]
 
     @app.call_tool()
     async def call_tool(name: str, arguments: Dict[str, Any]) -> List["types.TextContent"]:
+        """Chạy một tool MS365 và trả kết quả về dưới dạng văn bản."""
         return [types.TextContent(type="text", text=_dispatch(name, arguments or {}))]
 
     return app
 
 
 def main() -> None:
+    """Điểm vào khi chạy như tiến trình con: phục vụ MCP qua stdio."""
     import anyio
     from mcp.server.stdio import stdio_server
 
     app = build_server()
 
     async def _run() -> None:
+        """Vòng lặp phục vụ, đọc/ghi trên stdio cho tới khi tiến trình cha đóng."""
         async with stdio_server() as (read, write):
             await app.run(read, write, app.create_initialization_options())
 
diff --git a/mcp_servers/project_context/foundation.py b/mcp_servers/project_context/foundation.py
index 675d638..1ee95b5 100644
--- a/mcp_servers/project_context/foundation.py
+++ b/mcp_servers/project_context/foundation.py
@@ -17,6 +17,11 @@ class ContractModel(BaseModel):
 
 
 class IdentityContext(ContractModel):
+    """Danh tính người gọi kèm phạm vi đã được cấp.
+
+    ``granted_scopes`` là ``frozenset`` để bản ghi danh tính không bị sửa
+    trên đường đi giữa các tầng.
+    """
     actor_id: str = Field(min_length=1, max_length=256)
     org_unit: str = Field(min_length=1, max_length=128)
     customer: str = Field(min_length=1, max_length=128)
@@ -25,6 +30,10 @@ class IdentityContext(ContractModel):
 
 
 class SourceCitation(ContractModel):
+    """Trích dẫn nguồn cho một mẩu thông tin: hệ thống nào, URL nào, bản nào, lấy lúc nào.
+
+    Bắt buộc có để Agent trả lời kèm nguồn kiểm chứng được, không bịa.
+    """
     system: str = Field(min_length=1, max_length=64)
     url: AnyUrl
     revision: str = Field(min_length=1, max_length=256)
@@ -33,20 +42,31 @@ class SourceCitation(ContractModel):
 
 @dataclass(frozen=True)
 class DispatchResult:
+    """Kết quả một lượt gọi tool: thành công hay không, kèm payload trả cho Agent."""
     ok: bool
     payload: dict[str, Any]
 
 
 class PolicyDecisionPoint(Protocol):
-    def decide(self, identity: IdentityContext, tool_name: str, project_id: str) -> bool: ...
+    """Nơi quyết định một danh tính có được gọi một tool trên một project hay không."""
+    def decide(self, identity: IdentityContext, tool_name: str, project_id: str) -> bool:
+        """``True`` nếu cho phép lượt gọi này."""
+        ...
 
 
 class CredentialResolver(Protocol):
-    def resolve(self, identity: IdentityContext, tool_name: str) -> Any: ...
+    """Nơi cấp thông tin xác thực cho tool, tách khỏi chỗ dùng nó."""
+    def resolve(self, identity: IdentityContext, tool_name: str) -> Any:
+        """Trả về thông tin xác thực cho danh tính và tool tương ứng."""
+        ...
 
 
 @dataclass(frozen=True)
 class ProjectContextRuntime:
+    """Bộ ba mà mọi lượt gọi tool cần: danh tính, cổng chính sách, nơi cấp thông tin xác thực.
+
+    Bất biến (``frozen``) — một lượt gọi không được đổi bối cảnh của lượt khác.
+    """
     identity: IdentityContext
     policy: PolicyDecisionPoint
     credential_resolver: CredentialResolver
@@ -56,6 +76,9 @@ class ProviderError(RuntimeError):
     """A provider failure with a caller-safe message and retry classification."""
 
     def __init__(self, code: str, message: str, *, retryable: bool) -> None:
+        """``safe_message`` là phần được phép hiện cho người dùng; ``retryable`` cho bên
+        gọi biết thử lại có ích không, thay vì bắt họ đoán từ chuỗi lỗi.
+        """
         super().__init__(message)
         self.code = code
         self.safe_message = message
@@ -67,6 +90,7 @@ ToolHandler = Callable[[ContractModel, Any], dict[str, Any]]
 
 @dataclass(frozen=True)
 class ToolTemplate:
+    """Khai báo một tool MCP: tên, mô tả, kiểu vào/ra, và hàm xử lý."""
     name: str
     description: str
     input_model: type[ContractModel]
@@ -74,6 +98,7 @@ class ToolTemplate:
     handler: ToolHandler
 
     def declaration(self) -> dict[str, Any]:
+        """Bản khai báo theo đúng định dạng MCP, schema sinh thẳng từ model Pydantic."""
         return {
             "name": self.name,
             "description": self.description,
@@ -91,6 +116,12 @@ def error_result(
     suggested_action: str,
     correlation_id: str,
 ) -> DispatchResult:
+    """Dựng một ``DispatchResult`` lỗi theo đúng khuôn chung.
+
+    Mọi lỗi trả cho Agent đều phải có ``correlation_id`` để dò lại trong
+    nhật ký, và ``suggested_action`` để Agent biết nên làm gì tiếp thay vì
+    chỉ dừng.
+    """
     return DispatchResult(
         ok=False,
         payload={
diff --git a/mcp_servers/project_context/providers/change.py b/mcp_servers/project_context/providers/change.py
index 9464363..627159e 100644
--- a/mcp_servers/project_context/providers/change.py
+++ b/mcp_servers/project_context/providers/change.py
@@ -8,11 +8,24 @@ from ..foundation import IdentityContext, ProviderError
 
 
 class ChangeProvider(Protocol):
-    def get_change_context(self, **arguments: Any) -> dict[str, Any]: ...
+    """Nguồn cấp bối cảnh thay đổi (commit, PR) cho một project.
+
+    Chỉ là hợp đồng: bản cài đặt thật được nối vào qua ``build_provider``.
+    """
+    def get_change_context(self, **arguments: Any) -> dict[str, Any]:
+        """Trả về bối cảnh thay đổi (commit, PR) theo tham số của tool."""
+        ...
 
 
 class UnconfiguredChangeProvider:
+    """Bản thay thế khi chưa cấu hình nguồn thay đổi (commit, PR) thật.
+
+    Luôn ném lỗi ``UNAVAILABLE`` thay vì trả dữ liệu rỗng — rỗng sẽ bị Agent
+    hiểu nhầm là "tra rồi, không có gì", còn lỗi thì nói đúng sự thật là
+    chưa có nguồn nào được nối.
+    """
     def get_change_context(self, **arguments: Any) -> dict[str, Any]:
+        """Luôn báo chưa cấu hình; không cho thử lại."""
         raise ProviderError(
             "UNAVAILABLE",
             "The change provider is not configured for this environment.",
diff --git a/mcp_servers/project_context/providers/issue.py b/mcp_servers/project_context/providers/issue.py
index 665db9b..9a57632 100644
--- a/mcp_servers/project_context/providers/issue.py
+++ b/mcp_servers/project_context/providers/issue.py
@@ -8,11 +8,24 @@ from ..foundation import IdentityContext, ProviderError
 
 
 class IssueProvider(Protocol):
-    def get_issue_context(self, **arguments: Any) -> dict[str, Any]: ...
+    """Nguồn cấp bối cảnh issue/ticket cho một project.
+
+    Chỉ là hợp đồng: bản cài đặt thật được nối vào qua ``build_provider``.
+    """
+    def get_issue_context(self, **arguments: Any) -> dict[str, Any]:
+        """Trả về bối cảnh issue/ticket theo tham số của tool."""
+        ...
 
 
 class UnconfiguredIssueProvider:
+    """Bản thay thế khi chưa cấu hình nguồn issue/ticket thật.
+
+    Luôn ném lỗi ``UNAVAILABLE`` thay vì trả dữ liệu rỗng — rỗng sẽ bị Agent
+    hiểu nhầm là "tra rồi, không có gì", còn lỗi thì nói đúng sự thật là
+    chưa có nguồn nào được nối.
+    """
     def get_issue_context(self, **arguments: Any) -> dict[str, Any]:
+        """Luôn báo chưa cấu hình; không cho thử lại."""
         raise ProviderError(
             "UNAVAILABLE",
             "The issue provider is not configured for this environment.",
diff --git a/mcp_servers/project_context/providers/knowledge.py b/mcp_servers/project_context/providers/knowledge.py
index 33b088a..7d8c8d0 100644
--- a/mcp_servers/project_context/providers/knowledge.py
+++ b/mcp_servers/project_context/providers/knowledge.py
@@ -8,11 +8,24 @@ from ..foundation import IdentityContext, ProviderError
 
 
 class KnowledgeProvider(Protocol):
-    def search_knowledge(self, **arguments: Any) -> dict[str, Any]: ...
+    """Nguồn cấp bối cảnh tri thức nội bộ cho một project.
+
+    Chỉ là hợp đồng: bản cài đặt thật được nối vào qua ``build_provider``.
+    """
+    def search_knowledge(self, **arguments: Any) -> dict[str, Any]:
+        """Trả về bối cảnh tri thức nội bộ theo tham số của tool."""
+        ...
 
 
 class UnconfiguredKnowledgeProvider:
+    """Bản thay thế khi chưa cấu hình nguồn tri thức nội bộ thật.
+
+    Luôn ném lỗi ``UNAVAILABLE`` thay vì trả dữ liệu rỗng — rỗng sẽ bị Agent
+    hiểu nhầm là "tra rồi, không có gì", còn lỗi thì nói đúng sự thật là
+    chưa có nguồn nào được nối.
+    """
     def search_knowledge(self, **arguments: Any) -> dict[str, Any]:
+        """Luôn báo chưa cấu hình; không cho thử lại."""
         raise ProviderError(
             "UNAVAILABLE",
             "The knowledge provider is not configured for this environment.",
diff --git a/mcp_servers/project_context/registry.py b/mcp_servers/project_context/registry.py
index bd6a78c..33dd220 100644
--- a/mcp_servers/project_context/registry.py
+++ b/mcp_servers/project_context/registry.py
@@ -20,4 +20,5 @@ TOOL_NAMES = tuple(tool.name for tool in TOOLS)
 
 
 def tool_declarations() -> list[dict[str, Any]]:
+    """Danh sách khai báo của mọi tool đã đăng ký, để trả về cho ``list_tools``."""
     return [tool.declaration() for tool in TOOLS]
diff --git a/mcp_servers/project_context/runtime.py b/mcp_servers/project_context/runtime.py
index 99b528e..1a089ed 100644
--- a/mcp_servers/project_context/runtime.py
+++ b/mcp_servers/project_context/runtime.py
@@ -31,6 +31,9 @@ class ProjectScopePolicy:
     """Pilot policy: read scope and exact identity-bound project are both mandatory."""
 
     def decide(self, identity: IdentityContext, tool_name: str, project_id: str) -> bool:
+        """Chỉ cho phép khi danh tính có phạm vi ``read`` VÀ project khớp đúng
+        project gắn với danh tính đó — không cho đọc chéo project.
+        """
         return "read" in identity.granted_scopes and project_id == identity.project
 
 
@@ -43,7 +46,11 @@ PROVIDER_FACTORIES: dict[str, Callable[[IdentityContext], Any]] = {
 
 @dataclass(frozen=True)
 class ProjectProviderResolver:
+    """Tra provider thật cho từng tool theo bảng ``PROVIDER_FACTORIES``."""
     def resolve(self, identity: IdentityContext, tool_name: str) -> Any:
+        """Dựng provider cho một tool; tool chưa đăng ký thì báo ``NOT_FOUND`` và
+        không cho thử lại.
+        """
         factory = PROVIDER_FACTORIES.get(tool_name)
         if factory is None:
             raise ProviderError("NOT_FOUND", "The requested tool is not registered.", retryable=False)
@@ -51,6 +58,11 @@ class ProjectProviderResolver:
 
 
 def _required_environment(name: str) -> str:
+    """Đọc một biến môi trường bắt buộc; thiếu thì dừng ngay lúc khởi động.
+
+    Thà không chạy còn hơn chạy với cấu hình khuyết rồi lỗi giữa chừng ở một
+    lượt gọi tool nào đó.
+    """
     value = os.environ.get(name, "").strip()
     if not value:
         raise RuntimeError(f"Project Context MCP cannot start: required setting {name} is missing")
diff --git a/mcp_servers/project_context/server.py b/mcp_servers/project_context/server.py
index 0f83616..a1a1eea 100644
--- a/mcp_servers/project_context/server.py
+++ b/mcp_servers/project_context/server.py
@@ -99,6 +99,11 @@ def dispatch(
 
 
 def build_server(runtime: Optional[ProjectContextRuntime] = None):
+    """Dựng máy chủ MCP Project Context.
+
+    ``runtime`` để trống thì lấy bộ mặc định đọc từ biến môi trường; test
+    truyền vào bộ giả để không cần cấu hình thật.
+    """
     from mcp import types
     from mcp.server.lowlevel import Server
 
@@ -108,10 +113,16 @@ def build_server(runtime: Optional[ProjectContextRuntime] = None):
 
     @app.list_tools()
     async def list_tools() -> list[types.Tool]:
+        """Trả về khai báo của mọi tool đã đăng ký."""
         return [types.Tool(**declaration) for declaration in tool_declarations()]
 
     @app.call_tool()
     async def call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
+        """Chạy một tool và trả kết quả.
+
+        Luôn kèm payload dạng văn bản JSON; chỉ khi thành công mới đính thêm
+        ``structuredContent``, còn lỗi thì bật ``isError``.
+        """
         result = dispatch(name, arguments or {}, app_runtime)
         return types.CallToolResult(
             content=[types.TextContent(
@@ -126,12 +137,14 @@ def build_server(runtime: Optional[ProjectContextRuntime] = None):
 
 
 def main() -> None:
+    """Điểm vào khi chạy như tiến trình con: phục vụ MCP qua stdio."""
     import anyio
     from mcp.server.stdio import stdio_server
 
     app = build_server()
 
     async def _run() -> None:
+        """Vòng lặp phục vụ, đọc/ghi trên stdio cho tới khi tiến trình cha đóng."""
         async with stdio_server() as (read, write):
             await app.run(read, write, app.create_initialization_options())
 
diff --git a/mcp_servers/project_context/tools/change_context.py b/mcp_servers/project_context/tools/change_context.py
index 37d5ab2..8a146ca 100644
--- a/mcp_servers/project_context/tools/change_context.py
+++ b/mcp_servers/project_context/tools/change_context.py
@@ -12,6 +12,10 @@ from ..foundation import ContractModel, SourceCitation, ToolTemplate
 
 
 class ChangeContextInput(ContractModel):
+    """Tham số vào của ``get_project_change_context``: project và mã thay đổi.
+
+    ``detail`` chọn độ dài kết quả, ``cursor`` để lấy trang tiếp khi bị cắt bớt.
+    """
     project_id: str = Field(min_length=1, max_length=128)
     change_id: str = Field(min_length=1, max_length=128)
     detail: Literal["summary", "standard", "full"] = "standard"
@@ -19,6 +23,11 @@ class ChangeContextInput(ContractModel):
 
 
 class ChangeContextOutput(ContractModel):
+    """Kết quả trả về: mô tả một commit/PR/MR kèm file, commit và issue liên quan.
+
+    ``source`` là trích dẫn nguồn bắt buộc; ``truncated``/``next_cursor`` cho
+    Agent biết còn dữ liệu chưa lấy hết.
+    """
     correlation_id: str
     project_id: str
     change_id: str
@@ -38,6 +47,7 @@ class ChangeContextOutput(ContractModel):
 
 
 def _handle(arguments: ContractModel, provider: Any) -> dict[str, Any]:
+    """Kiểm tham số theo schema rồi chuyển sang provider đã được cấp cho lượt gọi này."""
     request = ChangeContextInput.model_validate(arguments)
     return provider.get_change_context(**request.model_dump())
 
diff --git a/mcp_servers/project_context/tools/issue_context.py b/mcp_servers/project_context/tools/issue_context.py
index ed32f6e..74ecd7e 100644
--- a/mcp_servers/project_context/tools/issue_context.py
+++ b/mcp_servers/project_context/tools/issue_context.py
@@ -12,6 +12,10 @@ from ..foundation import ContractModel, SourceCitation, ToolTemplate
 
 
 class IssueContextInput(ContractModel):
+    """Tham số vào của ``get_project_issue_context``: project và mã issue.
+
+    ``detail`` chọn độ dài kết quả, ``cursor`` để lấy trang tiếp khi bị cắt bớt.
+    """
     project_id: str = Field(min_length=1, max_length=128)
     issue_key: str = Field(min_length=1, max_length=128)
     detail: Literal["summary", "standard", "full"] = "standard"
@@ -19,6 +23,7 @@ class IssueContextInput(ContractModel):
 
 
 class RelatedItem(ContractModel):
+    """Một mục liên quan tới issue (issue khác, PR, tài liệu) kèm loại quan hệ."""
     item_id: str
     relation: str
     title: str
@@ -26,6 +31,11 @@ class RelatedItem(ContractModel):
 
 
 class IssueContextOutput(ContractModel):
+    """Kết quả trả về: tiêu đề, trạng thái, mô tả, tiêu chí nghiệm thu và các mục liên quan.
+
+    ``source`` là trích dẫn nguồn bắt buộc; ``truncated``/``next_cursor`` cho
+    Agent biết còn dữ liệu chưa lấy hết.
+    """
     correlation_id: str
     project_id: str
     issue_key: str
@@ -42,6 +52,7 @@ class IssueContextOutput(ContractModel):
 
 
 def _handle(arguments: ContractModel, provider: Any) -> dict[str, Any]:
+    """Kiểm tham số theo schema rồi chuyển sang provider đã được cấp cho lượt gọi này."""
     request = IssueContextInput.model_validate(arguments)
     return provider.get_issue_context(**request.model_dump())
 
diff --git a/mcp_servers/project_context/tools/knowledge_search.py b/mcp_servers/project_context/tools/knowledge_search.py
index 3eed718..5576963 100644
--- a/mcp_servers/project_context/tools/knowledge_search.py
+++ b/mcp_servers/project_context/tools/knowledge_search.py
@@ -12,6 +12,10 @@ from ..foundation import ContractModel, SourceCitation, ToolTemplate
 
 
 class KnowledgeSearchInput(ContractModel):
+    """Tham số vào của ``search_project_knowledge``: project và câu truy vấn.
+
+    ``top_k`` chặn trong 1..20 để một lượt tra không nuốt hết cửa sổ ngữ cảnh.
+    """
     project_id: str = Field(min_length=1, max_length=128)
     query: str = Field(min_length=2, max_length=1000)
     detail: Literal["summary", "standard", "full"] = "standard"
@@ -21,6 +25,7 @@ class KnowledgeSearchInput(ContractModel):
 
 
 class KnowledgeItem(ContractModel):
+    """Một đoạn tài liệu khớp truy vấn: trích đoạn, điểm số 0..1 và nguồn."""
     document_id: str
     chunk_id: str
     title: str
@@ -30,6 +35,7 @@ class KnowledgeItem(ContractModel):
 
 
 class KnowledgeSearchOutput(ContractModel):
+    """Kết quả trả về: danh sách đoạn khớp đã xếp hạng, mỗi đoạn kèm trích dẫn nguồn."""
     correlation_id: str
     project_id: str
     query: str
@@ -41,6 +47,7 @@ class KnowledgeSearchOutput(ContractModel):
 
 
 def _handle(arguments: ContractModel, provider: Any) -> dict[str, Any]:
+    """Kiểm tham số theo schema rồi chuyển sang provider đã được cấp cho lượt gọi này."""
     request = KnowledgeSearchInput.model_validate(arguments)
     return provider.search_knowledge(**request.model_dump())
 
diff --git a/paths.py b/paths.py
index ce1e6ae..d16ef45 100644
--- a/paths.py
+++ b/paths.py
@@ -51,6 +51,7 @@ def detect_onedrive_roots() -> List[Path]:
 
 
 def primary_onedrive_root() -> Path | None:
+    """Thư mục OneDrive chính (cái đầu tiên tìm thấy); ``None`` nếu máy không có."""
     roots = detect_onedrive_roots()
     return roots[0] if roots else None
 
diff --git a/presentation/chat/__init__.py b/presentation/chat/__init__.py
index e40d803..d60873e 100644
--- a/presentation/chat/__init__.py
+++ b/presentation/chat/__init__.py
@@ -17,11 +17,14 @@ from .chat_output_panel import OutputPanelMixin
 from .chat_panel import ChatPanel
 from .composer_widget import Composer, ComposerWidget
 
+# ``ChatOutputPanelMixin`` từng nằm trong danh sách này nhưng module không hề
+# export cái tên đó — tên thật là ``OutputPanelMixin`` (đã có ở dưới). Khai một
+# tên không tồn tại làm ``from ... import *`` ném AttributeError, và ``__all__``
+# thì không có bước kiểm nào bắt được. Đã gỡ.
 __all__ = [
     "AttachmentMixin",
     "AudioRecorderWidget",
     "ChatHistoryWidget",
-    "ChatOutputPanelMixin",
     "ChatPanel",
     "ChatView",
     "Composer",
diff --git a/presentation/chat/attachment_picker.py b/presentation/chat/attachment_picker.py
index f04dc25..f198710 100644
--- a/presentation/chat/attachment_picker.py
+++ b/presentation/chat/attachment_picker.py
@@ -24,12 +24,14 @@ class AttachmentMixin:
 
     def _on_attachments_added(self, paths: List[str]) -> None:
         # Push attachments into the Input box as soon as they're attached.
+        """Tệp vừa được đính kèm: đưa luôn vào mục "Tệp đầu vào" để người dùng thấy ngay."""
         for p in paths:
             self.input_section.add(p)
 
     def _on_attachment_removed(self, path: str) -> None:
         # A file added by mistake was removed in the composer — drop it from the
         # Input panel too (only matters before the message is sent).
+        """Gỡ tệp đính kèm nhầm khỏi cả mục "Tệp đầu vào" (chỉ có ý nghĩa trước khi gửi)."""
         self.input_section.remove(path)
 
     def _attach_char_limit(self) -> int:
@@ -137,6 +139,9 @@ class AttachmentMixin:
             return result
 
         def progress(page: int, total: int, _name=name) -> None:
+            """Báo tiến độ trích nội dung, chỉ với tệp nhiều trang — tệp một trang thì dòng
+            tiến độ chỉ làm nhiễu.
+            """
             if notify is not None and total > 1:
                 notify({"type": "notice", "level": "progress",
                         "text": tr("chat.reading_progress", name=_name, page=page, total=total)})
diff --git a/presentation/chat/audio_recorder_widget.py b/presentation/chat/audio_recorder_widget.py
index adf6d25..f5356d2 100644
--- a/presentation/chat/audio_recorder_widget.py
+++ b/presentation/chat/audio_recorder_widget.py
@@ -38,6 +38,7 @@ class AudioRecorderWidget(QWidget):
     audio_ready = Signal(bytes, str)  # audio_data, format (e.g., 'wav')
 
     def __init__(self, parent: Optional[QWidget] = None) -> None:
+        """Dựng nút ghi âm kèm đồng hồ đếm giây, nhịp 1 giây."""
         super().__init__(parent)
         self._is_recording = False
         self._elapsed_seconds = 0
diff --git a/presentation/chat/chat_agents.py b/presentation/chat/chat_agents.py
index 256afc2..2d0d275 100644
--- a/presentation/chat/chat_agents.py
+++ b/presentation/chat/chat_agents.py
@@ -36,6 +36,7 @@ class ChatAgentsMixin:
         return self._model or tr("chat.provider_default_short")
 
     def _on_agent_changed(self, _i: int) -> None:
+        """Đổi agent trong bộ chọn: agent quản trị thì lấy cả provider/model riêng của nó."""
         data = self.agent_combo.currentData() or ""
         if isinstance(data, str) and data.startswith(self._ADMIN_AGENT_PREFIX):
             # An Admin-defined agent preset (Monitoring → Agents Admin): runs
@@ -94,6 +95,7 @@ class ChatAgentsMixin:
         self._agent_provider = name
 
         def job(worker: AgentWorker):
+            """Chạy nền: hỏi provider danh sách model để đổ vào bộ chọn agent."""
             error = ""
             try:
                 prov = self.ctx.build_provider_for(name)
@@ -105,6 +107,7 @@ class ChatAgentsMixin:
             return {"models": models, "keep": keep, "error": error}
 
         def done(result) -> None:
+            """Đổ danh sách vào bộ chọn, giữ nguyên lựa chọn trước đó nếu còn."""
             self._populate_agents(result.get("models", []), result.get("keep", ""))
             # Surface the REAL reason models didn't load (network/auth/config)
             # instead of silently falling back to "(provider default)".
@@ -118,6 +121,11 @@ class ChatAgentsMixin:
         w.start()
 
     def _populate_agents(self, models, keep: str) -> None:
+        """Đổ danh sách vào bộ chọn Agent.
+
+        Bộ chọn này thực chất là bộ chọn MODEL: danh sách model của provider đang
+        dùng, cộng thêm các agent quản trị có provider/model riêng.
+        """
         self.agent_combo.blockSignals(True)
         self.agent_combo.clear()
         # The Agent picker is a MODEL picker — the raw model list of the active
diff --git a/presentation/chat/chat_bubble_style.py b/presentation/chat/chat_bubble_style.py
index 05f85bb..c228db4 100644
--- a/presentation/chat/chat_bubble_style.py
+++ b/presentation/chat/chat_bubble_style.py
@@ -53,15 +53,21 @@ class _TimelineGutter(QWidget):
     (Claude-Code style) instead of separate boxes."""
 
     def __init__(self, role: str):
+        """Dải dọc bên trái mỗi bong bóng, màu theo vai người nói."""
         super().__init__()
         self._role = role
         self.setFixedWidth(22)
 
     def set_role(self, role: str) -> None:
+        """Đổi vai trò (người dùng/trợ lý/tool/lỗi) và vẽ lại chấm mốc."""
         self._role = role
         self.update()
 
     def paintEvent(self, _e):  # noqa: N802
+        """Vẽ dải mốc thời gian bên trái bong bóng: một đường mờ chạy suốt chiều cao
+        cộng một chấm màu theo vai trò — nối lại thành một trục liền mạch cho cả
+        dòng thời gian.
+        """
         p = QPainter(self)
         p.setRenderHint(QPainter.Antialiasing)
         tok = _p()
@@ -87,6 +93,7 @@ def _diff_legend(diff_text: str) -> str:
     p = _p()
 
     def pill(bg: str, fg: str, key: str) -> str:
+        """Một nhãn viên thuốc (nền + chữ) trong chú giải diff."""
         return (f'<span style="background:{bg}; color:{fg}; padding:1px 8px; '
                 f'border-radius:4px; font-weight:600;">{html.escape(tr(key))}</span>')
 
@@ -149,6 +156,7 @@ class ThinkingIndicator(QWidget):
     running rather than stuck."""
 
     def __init__(self):
+        """Dòng "đang nghĩ…" hiện trong lúc chờ model trả lời."""
         super().__init__()
         lay = QHBoxLayout(self)
         lay.setContentsMargins(14, 2, 14, 4)
@@ -167,6 +175,7 @@ class ThinkingIndicator(QWidget):
         on_language_changed(self._render)
 
     def start(self, label_key: str = "chat.running") -> None:
+        """Bật chỉ báo "đang nghĩ" kèm nhãn và bộ đếm chấm động."""
         self._base_key = label_key
         self._override = None
         self._ticks = 0
@@ -176,6 +185,7 @@ class ThinkingIndicator(QWidget):
             self._timer.start()
 
     def set_label(self, label_key: str) -> None:
+        """Đổi nhãn đang hiện (ví dụ từ "đang chạy" sang "đang gọi tool")."""
         if label_key != self._base_key:
             self._base_key = label_key
             self._override = None
@@ -189,14 +199,17 @@ class ThinkingIndicator(QWidget):
         self._render()
 
     def stop(self) -> None:
+        """Tắt chỉ báo và dừng bộ đếm."""
         self._timer.stop()
         self._override = None
         self.setVisible(False)
 
     def _tick(self) -> None:
+        """Một nhịp của hiệu ứng chấm động: tăng bộ đếm rồi vẽ lại nhãn."""
         self._ticks += 1
         self._render()
 
     def _render(self) -> None:
+        """Vẽ lại dòng trạng thái: nhãn hiện tại cộng chấm động theo bộ đếm."""
         base = self._override if self._override is not None else tr(self._base_key)
         self._label.setText(format_status_line(base, self._ticks))
diff --git a/presentation/chat/chat_event_stream.py b/presentation/chat/chat_event_stream.py
index 8ac56d1..787d220 100644
--- a/presentation/chat/chat_event_stream.py
+++ b/presentation/chat/chat_event_stream.py
@@ -17,13 +17,21 @@ from PySide6.QtCore import Qt, Signal
 from ...core.worker import AgentWorker
 from ...i18n import tr
 from ...state import AppContext
-from ...ui.composer import Composer
+# Nhập thẳng từ chỗ ở thật, không đi qua vỏ chuyển tiếp ``ui/composer.py``:
+# vỏ ấy lại nhập ngược vào gói này, nên đi vòng qua nó tạo một chu trình
+# import — ``import cowork_local.ui.composer`` khi chưa nạp gói này sẽ hỏng.
+from .composer_widget import Composer
 
 
 class ChatEventStreamMixin:
     """Xử lý sự kiện của một lượt. Trộn vào ChatPanel."""
 
     def _on_event(self, ctx: Dict[str, Any], ev: Dict[str, Any]) -> None:
+        """Nhận một sự kiện từ lượt chạy và vẽ vào dòng thời gian.
+
+        Trạng thái của lượt vẫn được cập nhật kể cả khi hội thoại này không còn hiện
+        trên màn — người dùng có thể quay lại và phải thấy đúng những gì đã xảy ra.
+        """
         etype = ev.get("type")
         # Track the in-progress state even while this turn is a detached background
         # job, so reopening its conversation can re-render the CURRENT task (partial
@@ -164,6 +172,12 @@ class ChatEventStreamMixin:
         # falling back to the global "confirm before running commands" setting.
         # Resolve on THIS turn's worker, never the latest — several turns may
         # be awaiting approval at once.
+        """Một tool cần phê duyệt trước khi chạy.
+
+        Tự đồng ý TRỪ KHI workspace này bật "hỏi trước khi chạy lệnh" (đặt riêng theo
+        workspace, không có thì lấy cấu hình chung). Trả lời phải gửi đúng worker của
+        LƯỢT NÀY, không phải worker mới nhất — có thể nhiều lượt cùng đang chờ duyệt.
+        """
         if self.ctx.project_confirm_commands():
             from ...ui.permission_dialog import PermissionDialog
 
diff --git a/presentation/chat/chat_history_widget.py b/presentation/chat/chat_history_widget.py
index 464048e..b1898ee 100644
--- a/presentation/chat/chat_history_widget.py
+++ b/presentation/chat/chat_history_widget.py
@@ -43,6 +43,11 @@ class MessageBubble(QFrame):
 
     def __init__(self, role: str, title: str = "", collapsible: bool = False,
                  collapsed: bool = True):
+        """Một bong bóng tin nhắn.
+
+        ``collapsible`` dành cho khối dài (kết quả tool, suy nghĩ của model): chúng
+        mở sẵn thì đẩy phần trả lời thật ra khỏi màn hình.
+        """
         super().__init__()
         self.role = role
         self._text = ""
@@ -92,12 +97,16 @@ class MessageBubble(QFrame):
             self._update_head()
 
     def _toggle_body(self) -> None:
+        """Gập/mở phần thân bong bóng khi bấm vào dòng tiêu đề."""
         self.body.setVisible(not self.body.isVisible())
         if self.body.isVisible():
             self._autosize()
         self._update_head()
 
     def _update_head(self) -> None:
+        """Vẽ lại dòng tiêu đề: mũi tên gập/mở, và khi đang gập thì kèm 70 ký tự
+        đầu làm xem trước — để nhìn dòng tiêu đề là đoán được bên trong có gì.
+        """
         if not self._head:
             return
         expanded = self.body.isVisible()
@@ -153,10 +162,12 @@ class MessageBubble(QFrame):
         return None
 
     def append_delta(self, delta: str) -> None:
+        """Nối thêm một mẩu văn bản đang phát dần từ model rồi vẽ lại dạng markdown."""
         self._text += delta
         self.set_markdown(self._text)
 
     def set_markdown(self, text: str) -> None:
+        """Đặt toàn bộ nội dung, hiển thị dạng markdown, rồi co giãn lại chiều cao."""
         self._text = text
         self.body.setMarkdown(text)
         self._autosize()
@@ -164,6 +175,7 @@ class MessageBubble(QFrame):
             self._update_head()
 
     def set_plain(self, text: str) -> None:
+        """Đặt toàn bộ nội dung dạng văn bản thuần (không diễn giải markdown)."""
         self._text = text
         self.body.setPlainText(text)
         self._autosize()
@@ -171,6 +183,7 @@ class MessageBubble(QFrame):
             self._update_head()
 
     def append_plain(self, delta: str) -> None:
+        """Nối thêm một mẩu văn bản thuần đang phát dần (dùng cho log tool)."""
         self._text += delta
         self.set_plain(self._text)
 
@@ -197,12 +210,14 @@ class MessageBubble(QFrame):
         self._content_layout.addWidget(lbl)
 
     def add_delete_link(self, callback) -> None:
+        """Gắn liên kết "xoá" màu cảnh báo dưới bong bóng, bấm vào thì gọi ``callback``."""
         link = QLabel(f'<a href="#del" style="color:{_p().danger};">{tr("chat.delete_link")}</a>')
         link.setToolTip(tr("chat.delete_tooltip"))
         link.linkActivated.connect(lambda *_: callback())
         self._content_layout.addWidget(link)
 
     def add_folder_link(self, folder: str, label: str | None = None) -> None:
+        """Gắn liên kết mở thư mục kết quả trong trình quản lý tệp của hệ điều hành."""
         label = label or tr("chat.open_workspace")
         link = QLabel(f'<a href="#open" style="color:{_p().accent};">{label}</a>')
         link.setToolTip(str(folder))
@@ -229,6 +244,12 @@ class MessageBubble(QFrame):
             self._content_layout.addWidget(file_link)
 
     def _autosize(self) -> None:
+        """Đặt chiều cao bong bóng vừa đúng nội dung.
+
+        QTextBrowser không tự co giãn theo nội dung, nên phải tính tay. Chặn
+        trong khoảng 28..1200px: quá thấp thì mất chữ, quá cao thì một câu trả
+        lời dài chiếm trọn màn hình và không cuộn tới cái sau được.
+        """
         width = self.body.viewport().width()
         if width <= 0:
             width = 560  # sensible default before the widget is laid out
@@ -237,6 +258,7 @@ class MessageBubble(QFrame):
         self.body.setFixedHeight(max(28, min(height, 1200)))
 
     def resizeEvent(self, event):  # noqa: N802 - re-flow on width change
+        """Đổi bề rộng thì phải tính lại chiều cao — chữ xuống dòng khác đi."""
         super().resizeEvent(event)
         self._autosize()
 
@@ -249,6 +271,11 @@ class ChatView(QScrollArea):
     app switches between light and dark modes."""
 
     def __init__(self):
+        """Vùng cuộn chứa dòng thời gian tin nhắn.
+
+        Có một ``addStretch`` ở cuối để khi ít tin, chúng dồn lên trên thay vì trôi
+        giữa khung.
+        """
         super().__init__()
         self.setWidgetResizable(True)
         self._container = QWidget()
@@ -269,21 +296,29 @@ class ChatView(QScrollArea):
                 w.apply_theme()
 
     def _add(self, bubble: MessageBubble) -> MessageBubble:
+        """Chèn bong bóng vào cuối danh sách (trước phần đệm co giãn) rồi cuộn xuống."""
         # insert before the trailing stretch
         self._lay.insertWidget(self._lay.count() - 1, bubble)
         self._scroll_to_bottom()
         return bubble
 
     def add_user(self, text: str) -> MessageBubble:
+        """Thêm một tin nhắn của người dùng."""
         b = MessageBubble("user", tr("chat.you"))
         b.set_plain(text)
         return self._add(b)
 
     def add_assistant(self, title: str | None = None) -> MessageBubble:
+        """Thêm một bong bóng trả lời rỗng để model phát nội dung dần vào."""
         b = MessageBubble("assistant", title or tr("chat.assistant"))
         return self._add(b)
 
     def add_tool(self, title: str, body: str, ok: bool = True) -> MessageBubble:
+        """Thêm một bước tool (chạy lệnh, sinh mã, kết quả).
+
+        Chạy xuôi thì gập lại cho dòng thời gian ngắn gọn; lỗi thì mở sẵn vì đó
+        là thứ người dùng cần đọc ngay.
+        """
         # Tool steps (run command, generated code/diff, output) are collapsible to
         # keep the transcript short — collapsed when OK, expanded on error.
         b = MessageBubble("tool" if ok else "error", title, collapsible=True, collapsed=ok)
@@ -307,12 +342,17 @@ class ChatView(QScrollArea):
         return self._add(b)
 
     def add_reasoning(self, title: str | None = None) -> MessageBubble:
+        """Thêm hộp suy luận nội bộ của model — gập sẵn, mở ra đọc được.
+
+        Để người dùng thấy nó đang nghĩ mà không bị lấp kín khung chat.
+        """
         # The model's private reasoning — a collapsed, collapsible box so the user
         # can see it's thinking (and expand to read) without it flooding the chat.
         b = MessageBubble("tool", title or tr("chat.thinking"), collapsible=True, collapsed=True)
         return self._add(b)
 
     def add_error(self, text: str) -> MessageBubble:
+        """Thêm một bong bóng báo lỗi."""
         b = MessageBubble("error", tr("chat.error"))
         b.set_plain(text)
         return self._add(b)
@@ -331,6 +371,7 @@ class ChatView(QScrollArea):
         return self._add(b)
 
     def clear(self) -> None:
+        """Xoá sạch dòng thời gian, giữ lại phần đệm co giãn ở cuối."""
         while self._lay.count() > 1:
             item = self._lay.takeAt(0)
             w = item.widget()
@@ -344,6 +385,7 @@ class ChatView(QScrollArea):
         QTimer.singleShot(80, self._scroll_to_bottom)
 
     def _scroll_to_bottom(self) -> None:
+        """Kéo thanh cuộn xuống đáy ngay lập tức."""
         bar = self.verticalScrollBar()
         bar.setValue(bar.maximum())
 
diff --git a/presentation/chat/chat_input_box.py b/presentation/chat/chat_input_box.py
index 9bf3875..3d2f466 100644
--- a/presentation/chat/chat_input_box.py
+++ b/presentation/chat/chat_input_box.py
@@ -8,19 +8,11 @@ là thanh công cụ quanh nó.
 """
 from __future__ import annotations
 
-from datetime import datetime
-from pathlib import Path
-from typing import Dict, List
 from PySide6.QtCore import Qt, Signal
-from PySide6.QtGui import QImage, QKeyEvent
-from PySide6.QtWidgets import (
-    QFileDialog, QHBoxLayout, QLabel, QListView, QListWidget, QListWidgetItem,
-    QPlainTextEdit, QPushButton, QVBoxLayout, QWidget,
-)
-from ...config import CONFIG_DIR
-from ...i18n import on_language_changed, tr
-from ...theme import current_palette
-from ...ui.icons import icon, IconLabel
+from PySide6.QtGui import QKeyEvent
+from PySide6.QtWidgets import QListWidget, QListWidgetItem, QPlainTextEdit
+from ...i18n import tr
+from .composer_mime import paths_from_mime
 
 
 class _SkillPopup(QListWidget):
@@ -33,6 +25,11 @@ class _SkillPopup(QListWidget):
     an item selects it; the popup auto-hides when the input loses focus."""
 
     def __init__(self, parent=None):
+        """Danh sách gợi ý skill nổi lên khi gõ ``/``.
+
+        Đặt cờ không nhận tiêu điểm: bật lên mà cướp tiêu điểm thì con trỏ rời ô
+        nhập và người dùng gõ tiếp không được.
+        """
         super().__init__(parent)
         self.setWindowFlags(Qt.Tool | Qt.FramelessWindowHint
                             | Qt.WindowStaysOnTopHint | Qt.NoDropShadowWindowHint)
@@ -51,6 +48,11 @@ class _Input(QPlainTextEdit):
     MAX_HEIGHT = 220    # ~8 lines, then it scrolls
 
     def __init__(self):
+        """Ô soạn tin, nhận kéo–thả tệp.
+
+        Đặt phông riêng vì quy tắc ``*`` chung rơi về phông tiếng Nhật, làm một số
+        chữ tiếng Việt hiện sai dấu.
+        """
         super().__init__()
         self.setAcceptDrops(True)
         # Use a clean Latin/Vietnamese-friendly UI font for the input (the global
@@ -115,6 +117,11 @@ class _Input(QPlainTextEdit):
     def _maybe_show_skills(self) -> None:
         # One popup serves both commands: show skills while typing /skill, agents
         # while typing /agent (Cowork parity with the Co4E chat).
+        """Mở bảng gợi ý khi con trỏ đang đứng trên lệnh ``/skill`` hoặc ``/agent``.
+
+        Một bảng dùng chung cho cả hai lệnh, ``_popup_kind`` nhớ đang gợi ý loại
+        nào — giống hệt cách khung chat Co4E làm.
+        """
         stok = self._skill_token()
         if stok is not None:
             self._popup_kind = "skill"
@@ -130,6 +137,11 @@ class _Input(QPlainTextEdit):
         self._skill_popup.hide()
 
     def _populate_skill_popup(self, filt: str) -> None:
+        """Nạp danh sách skill khớp bộ lọc vào bảng gợi ý.
+
+        Gồm cả skill dựng sẵn để bảng vẫn dùng được khi người dùng chưa tạo skill
+        nào. Dấu ✓ đánh dấu skill đang bật. Dòng cuối luôn là lối mở trình quản lý.
+        """
         try:
             from ..core.skills import builtin_skills, list_skills
             # Include always-on built-ins so the picker is usable before the user
@@ -158,6 +170,7 @@ class _Input(QPlainTextEdit):
         self._skill_popup.setCurrentRow(0 if matches else self._skill_popup.count() - 1)
 
     def _populate_agent_popup(self, filt: str) -> None:
+        """Nạp danh sách agent khớp bộ lọc (dựng sẵn + admin + tự tạo) vào bảng gợi ý."""
         try:
             from ..core.agent_command import collect_agents
             agents = collect_agents("")   # built-ins + local admin + custom agents
@@ -179,6 +192,11 @@ class _Input(QPlainTextEdit):
         self._skill_popup.setCurrentRow(0 if matches else self._skill_popup.count() - 1)
 
     def _show_cmd_popup(self) -> None:
+        """Hiện bảng gợi ý ngay PHÍA TRÊN ô nhập, cao tối đa 7 dòng.
+
+        Đặt trên chứ không dưới vì ô nhập nằm sát đáy cửa sổ — thả xuống dưới là
+        rơi ra ngoài màn hình.
+        """
         rows = min(7, self._skill_popup.count())
         h = 10 + rows * 22
         self._skill_popup.resize(max(300, self.width()), h)
@@ -193,6 +211,11 @@ class _Input(QPlainTextEdit):
     def focusOutEvent(self, e) -> None:  # noqa: N802
         # The popup never grabs focus, so a click away lands here → dismiss it
         # (unless the click is on the popup itself, e.g. picking an item).
+        """Bấm ra chỗ khác thì ẩn bảng gợi ý.
+
+        Bảng không bao giờ giành focus, nên mọi cú bấm ra ngoài đều rơi vào đây —
+        trừ khi chuột đang ở trên chính bảng, tức người dùng đang chọn một mục.
+        """
         if not self._skill_popup.underMouse():
             self._skill_popup.hide()
         super().focusOutEvent(e)
@@ -206,6 +229,11 @@ class _Input(QPlainTextEdit):
             self._accept_skill(item)
 
     def _replace_token(self, tok, replacement: str) -> None:
+        """Thay đúng đoạn lệnh con trỏ đang đứng, giữ nguyên chữ trước và sau nó.
+
+        Nhờ vậy ``/skill:`` viết được ở giữa câu. Chặn tín hiệu lúc đặt lại nội
+        dung để không kích hoạt lại chính bảng gợi ý.
+        """
         pos = self.textCursor().position()
         start = tok[0] if tok else pos
         full = self.toPlainText()
@@ -221,6 +249,10 @@ class _Input(QPlainTextEdit):
         self.setFocus()
 
     def _accept_skill(self, item=None) -> None:
+        """Chọn một skill: thay đoạn ``/skill…`` bằng ``/skill:<slug>``.
+
+        Mục cuối cùng (``__manage__``) không phải skill mà là lối mở trình quản lý.
+        """
         item = item or self._skill_popup.currentItem()
         self._skill_popup.hide()
         if item is None:
@@ -236,6 +268,7 @@ class _Input(QPlainTextEdit):
         self._replace_token(self._skill_token(), f"/skill:{slug} ")
 
     def _accept_agent(self, item=None) -> None:
+        """Chọn một agent: thay đoạn ``/agent…`` bằng ``/agent:<slug>``."""
         item = item or self._skill_popup.currentItem()
         self._skill_popup.hide()
         if item is None:
@@ -248,6 +281,11 @@ class _Input(QPlainTextEdit):
     def _adjust_height(self, *_a) -> None:
         # QPlainTextEdit reports the document height in LINES (not pixels), so
         # convert via line spacing to get the real pixel height.
+        """Co giãn ô nhập theo số dòng đang gõ, chặn trong ``MIN_HEIGHT``..``MAX_HEIGHT``.
+
+        ``QPlainTextEdit`` trả chiều cao tài liệu theo SỐ DÒNG chứ không phải
+        pixel, nên phải nhân với khoảng cách dòng mới ra chiều cao thật.
+        """
         lines = self.document().size().height() or 1
         line_px = self.fontMetrics().lineSpacing()
         h = int(lines * line_px + 2 * self.frameWidth() + 12)
@@ -256,6 +294,9 @@ class _Input(QPlainTextEdit):
             self.setFixedHeight(h)
 
     def keyPressEvent(self, e: QKeyEvent) -> None:  # noqa: N802
+        """Điều hướng bảng gợi ý khi nó đang mở (lên/xuống/Enter/Esc); ngoài ra
+        Enter gửi tin nhắn còn Shift+Enter xuống dòng.
+        """
         if self._skill_popup.isVisible():
             k = e.key()
             if k in (Qt.Key_Down, Qt.Key_Up):
@@ -296,31 +337,36 @@ class _Input(QPlainTextEdit):
         super().keyPressEvent(e)
 
     def insertFromMimeData(self, source) -> None:  # noqa: N802 - paste
-        paths = _paths_from_mime(source)
+        """Dán ảnh hoặc đường dẫn tệp thì gắn thành tệp đính kèm thay vì dán chữ."""
+        paths = paths_from_mime(source)
         if paths:
             self.media_added.emit(paths)
             return
         super().insertFromMimeData(source)
 
     def canInsertFromMimeData(self, source) -> bool:  # noqa: N802
+        """Cho phép dán cả ảnh và danh sách tệp, không chỉ văn bản."""
         if source.hasImage() or source.hasUrls():
             return True
         return super().canInsertFromMimeData(source)
 
     def dragEnterEvent(self, e) -> None:  # noqa: N802
+        """Nhận kéo-thả ảnh và tệp vào ô nhập."""
         if e.mimeData().hasUrls() or e.mimeData().hasImage():
             e.acceptProposedAction()
             return
         super().dragEnterEvent(e)
 
     def dragMoveEvent(self, e) -> None:  # noqa: N802
+        """Giữ trạng thái nhận thả trong suốt lúc rê qua ô nhập."""
         if e.mimeData().hasUrls() or e.mimeData().hasImage():
             e.acceptProposedAction()
             return
         super().dragMoveEvent(e)
 
     def dropEvent(self, e) -> None:  # noqa: N802
-        paths = _paths_from_mime(e.mimeData())
+        """Thả tệp/ảnh vào ô nhập: gắn thành tệp đính kèm của lượt chat."""
+        paths = paths_from_mime(e.mimeData())
         if paths:
             self.media_added.emit(paths)
             e.acceptProposedAction()
diff --git a/presentation/chat/chat_output_panel.py b/presentation/chat/chat_output_panel.py
index eede096..2254729 100644
--- a/presentation/chat/chat_output_panel.py
+++ b/presentation/chat/chat_output_panel.py
@@ -110,10 +110,12 @@ class OutputPanelMixin:
         self.register_output(path)
 
     def on_inputs_added(self, paths: List[str]) -> None:
+        """Ghi nhận các tệp người dùng vừa đính kèm vào mục "Tệp đầu vào"."""
         for p in paths:
             self.input_section.add(p)
 
     def _open_io_item(self, path: str) -> None:
+        """Mở một tệp trong danh sách vào/ra bằng ứng dụng mặc định."""
         open_path(path)
 
     def _io_context_menu(self, section, pos) -> None:
@@ -139,6 +141,7 @@ class OutputPanelMixin:
             FileEditDialog(self.ctx, path, self).exec()
 
     def _rebuild_io(self) -> None:
+        """Dựng lại cả hai mục vào/ra từ trạng thái hiện tại của hội thoại."""
         self.input_section.clear()
         self.output_section.clear()
         for t in self.turns:
@@ -148,6 +151,7 @@ class OutputPanelMixin:
                 self.output_section.add(p)
 
     def _set_io_collapsed(self, collapsed: bool) -> None:
+        """Gập/mở khối vào/ra, đổi giữa panel đầy đủ và dải mỏng."""
         self._io_widget.setVisible(not collapsed)
         self._io_strip.setVisible(collapsed)
         strip_w = CollapseStrip.WIDTH + 2
diff --git a/presentation/chat/chat_panel.py b/presentation/chat/chat_panel.py
index efea766..01e845d 100644
--- a/presentation/chat/chat_panel.py
+++ b/presentation/chat/chat_panel.py
@@ -63,6 +63,11 @@ class ChatPanel(ChatLiveTurnsMixin, ChatPanelLayoutMixin, ChatEventStreamMixin,
                 ChatTurnRunnerMixin,
                 ChatSessionMixin,
                 QWidget):
+    """Khung chat dùng chung, ghép từ 8 mixin: bố cục, dòng sự kiện, tệp đính kèm,
+    ô vào/ra, bộ chọn agent, chạy lượt, lưu phiên và các lượt đang chạy.
+
+    Màn Cowork kế thừa lớp này và chỉ ghi đè phần khác biệt của mình.
+    """
     graph_event = Signal(str, dict)   # (session_name, event)
     turn_finished = Signal(dict)
     status_message = Signal(str)
@@ -71,6 +76,11 @@ class ChatPanel(ChatLiveTurnsMixin, ChatPanelLayoutMixin, ChatEventStreamMixin,
 
     def __init__(self, ctx: AppContext, kind: str, session_name: str,
                  placeholder_key: str = "composer.placeholder_default"):
+        """Dựng khung chat cho một bề mặt (``kind``) và mở một phiên mới.
+
+        ``placeholder_key`` là khoá i18n chứ không phải chữ sẵn, để đổi ngôn ngữ là
+        chữ gợi ý đổi theo.
+        """
         super().__init__()
         from ...core.history import new_session_id
 
@@ -208,6 +218,7 @@ class ChatPanel(ChatLiveTurnsMixin, ChatPanelLayoutMixin, ChatEventStreamMixin,
 
 
     def assistant_title(self) -> str:
+        """Nhãn hiện trên bong bóng trả lời; lớp con ghi đè để đổi tên trợ lý."""
         return tr("chat.assistant")
 
 
@@ -304,6 +315,7 @@ class ChatPanel(ChatLiveTurnsMixin, ChatPanelLayoutMixin, ChatEventStreamMixin,
 
     # ---- Teams auto-notify ------------------------------------------
     def _last_assistant_text(self) -> str:
+        """Nội dung trả lời cuối cùng của trợ lý trong hội thoại; '' nếu chưa có."""
         for m in reversed(self.messages):
             if m.get("role") == "assistant" and m.get("content"):
                 return m["content"]
diff --git a/presentation/chat/chat_session_store.py b/presentation/chat/chat_session_store.py
index 5ae9a74..ed8c9b0 100644
--- a/presentation/chat/chat_session_store.py
+++ b/presentation/chat/chat_session_store.py
@@ -62,9 +62,13 @@ class ChatSessionMixin:
 
 
     def _usage_label(self) -> str:
+        """Nhãn dùng để gom số liệu token của hội thoại này: tiêu đề, hoặc id phiên nếu
+        chưa có tiêu đề.
+        """
         return self.title or self.session_id
 
     def _session_events(self):
+        """Các bản ghi token thuộc riêng hội thoại này."""
         from ...core import usage_tracker as ut
         label = self._usage_label()
         return [e for e in ut.load_events()
@@ -100,6 +104,7 @@ class ChatSessionMixin:
         return snap
 
     def _session_cost_usd(self) -> float:
+        """Tổng chi phí (USD) của hội thoại này, tính theo bảng đơn giá hiện hành."""
         from ...core import model_pricing as mp
         return sum(mp.turn_cost_usd(e.get("model", ""), e.get("in", 0), e.get("out", 0),
                                     self.ctx.config) for e in self._session_events())
@@ -131,6 +136,11 @@ class ChatSessionMixin:
             f"{ut.format_cost(self._session_cost_usd(), pricing)}")
 
     def _autosave(self) -> None:
+        """Tự lưu hội thoại sau mỗi mốc an toàn.
+
+        Bỏ qua khi người dùng tắt tự lưu, và khi hội thoại chưa có tin nhắn nào của
+        người dùng — không tạo file rỗng cho một khung chat vừa mở ra rồi bỏ đấy.
+        """
         if not self.ctx.config.history.get("autosave", True):
             return
         if not any(m.get("role") == "user" for m in self.messages):
@@ -153,6 +163,7 @@ class ChatSessionMixin:
             pass  # autosave must never disrupt the UI
 
     def _maybe_notify_teams(self, result: Dict[str, Any]) -> None:
+        """Gửi nhắc qua Teams khi lượt chạy xong, nếu đã bật và đã cấu hình webhook."""
         teams = self.ctx.config.teams
         notifier = self.ctx.teams_notifier()
         if not (teams.get("notify_on_complete") and notifier.configured):
@@ -166,6 +177,7 @@ class ChatSessionMixin:
             facts["Status"] = "Error"
 
         def job(worker: AgentWorker):
+            """Chạy nền: gửi thẻ thông báo lên webhook Teams."""
             ok, detail = notifier.send(f"Cowork {self.session_name} — task done", summary[:1200], facts)
             return {"ok": ok, "detail": detail}
 
@@ -175,6 +187,11 @@ class ChatSessionMixin:
         w.start()
 
     def new_session(self) -> None:
+        """Mở một hội thoại mới.
+
+        Cho phép ngay cả khi đang chạy dở: lượt đang chạy vẫn tiếp tục ở nền và vẫn
+        ghi vào hội thoại cũ của nó.
+        """
         from ...core.history import new_session_id
 
         # Allowed while work is running: current turns keep going in the background.
@@ -276,6 +293,11 @@ class ChatSessionMixin:
         self.history_changed.emit()   # current view changed → refresh History highlight
 
     def _delete_turn(self, turn: Dict[str, Any]) -> None:
+        """Xoá một lượt khỏi hội thoại, hỏi trước khi xoá cả tệp nó đã tạo ra.
+
+        Liệt kê tối đa 12 tệp trong hộp xác nhận — dài hơn thì người dùng không đọc
+        mà chỉ bấm Đồng ý.
+        """
         files = [p for p in (turn.get("inputs", []) + turn.get("outputs", [])) if p]
         if files:
             preview = "\n".join("• " + str(p) for p in files[:12])
@@ -315,6 +337,7 @@ class ChatSessionMixin:
         msgs = list(self.messages)
 
         def _tok(ms):
+            """Ước lượng tổng token của một danh sách tin nhắn."""
             return sum(estimate_tokens(str(m.get("content", ""))) for m in ms)
 
         orig = _tok(msgs)
@@ -329,6 +352,9 @@ class ChatSessionMixin:
         old_tok = _tok(old) or 1               # target: digest < 25% of the OLD part
 
         def _digest(per_msg: int):
+            """Rút gọn các tin nhắn cũ thành tóm tắt một dòng mỗi tin, mỗi tin không quá
+            ``per_msg`` ký tự.
+            """
             parts = []
             for m in old:
                 c = str(m.get("content", "")).strip().replace("\n", " ")
diff --git a/presentation/chat/chat_turn_runner.py b/presentation/chat/chat_turn_runner.py
index 2b3f322..3dfe33d 100644
--- a/presentation/chat/chat_turn_runner.py
+++ b/presentation/chat/chat_turn_runner.py
@@ -16,7 +16,10 @@ from PySide6.QtCore import Qt, Signal
 from ...core.worker import AgentWorker
 from ...i18n import tr
 from ...state import AppContext
-from ...ui.composer import Composer
+# Nhập thẳng từ chỗ ở thật, không đi qua vỏ chuyển tiếp ``ui/composer.py``:
+# vỏ ấy lại nhập ngược vào gói này, nên đi vòng qua nó tạo một chu trình
+# import — ``import cowork_local.ui.composer`` khi chưa nạp gói này sẽ hỏng.
+from .composer_widget import Composer
 
 
 class ChatTurnRunnerMixin:
@@ -25,6 +28,11 @@ class ChatTurnRunnerMixin:
     def submit(self, text: str, attachments: Optional[List[str]] = None) -> None:
         # Composer only emits 'submitted' when not busy; queued items are
         # drained from here after each turn completes.
+        """Gửi một tin nhắn mới.
+
+        Composer chỉ phát ``submitted`` khi khung chat đang rảnh; tin xếp hàng được
+        rút dần trong :meth:`_drain_queue` sau mỗi lượt xong.
+        """
         self._start_turn(text, attachments or [])
 
     def run_prompts(self, prompts: List[str]) -> None:
@@ -48,6 +56,12 @@ class ChatTurnRunnerMixin:
         raise NotImplementedError
 
     def _start_turn(self, text: str, attachments: Optional[List[str]] = None) -> None:
+        """Khởi động một lượt chat: xử lý lệnh ``/skill``, dựng snapshot yêu cầu, rồi
+        chạy agent ở luồng nền.
+
+        Lệnh ``/skill`` dạng liệt kê/chọn được trả lời tại chỗ, không tốn một lượt
+        gọi model nào.
+        """
         attachments = attachments or []
         typed = text
         prefix, request, info = self._apply_skill_command(text)
@@ -128,6 +142,11 @@ class ChatTurnRunnerMixin:
                 _review=review_switch):
             # Worker thread: do the (possibly slow) attachment extraction here so
             # the UI stays responsive, then run the real agent job.
+            """Chạy nền: trích nội dung tệp đính kèm rồi mới chạy agent.
+
+            Trích ở luồng nền vì tệp lớn (PDF, Office) mất vài giây — làm ở luồng giao
+            diện là cả cửa sổ đứng hình.
+            """
             from ...core import usage_tracker
             usage_tracker.set_context(self.kind, self.title or self.session_id)
             body = self._augment(_t, _a, notify=worker.emit_event)
@@ -215,6 +234,12 @@ class ChatTurnRunnerMixin:
 
 
     def _on_finished(self, ctx: Dict[str, Any], result: Dict[str, Any]) -> None:
+        """Lượt chạy xong: dọn sandbox, giữ lại kế hoạch đã hoàn thành, rồi rút tiếp
+        tin trong hàng đợi.
+
+        Chỉ vẽ lên màn khi lượt này vẫn thuộc hội thoại ĐANG mở — người dùng có thể
+        đã chuyển sang hội thoại khác trong lúc chờ.
+        """
         live = self._turn_is_live(ctx)
         self._end_turn(ctx)
         self._cleanup_turn(ctx, True)   # promote this turn's output folder, if any
@@ -240,6 +265,7 @@ class ChatTurnRunnerMixin:
         self._drain_queue()
 
     def _on_failed(self, ctx: Dict[str, Any], err: str) -> None:
+        """Lượt chạy lỗi: huỷ thư mục kết quả tạm và hiện lỗi (nếu hội thoại còn đang mở)."""
         live = self._turn_is_live(ctx)
         self._end_turn(ctx)
         self._cleanup_turn(ctx, False)   # discard this turn's output sandbox
@@ -264,6 +290,12 @@ class ChatTurnRunnerMixin:
         # Start the NEXT queued message only while THIS conversation is idle (one
         # turn at a time here) and the global cap allows. Starting one flips
         # _view_busy() to True, so exactly one runs — the queue drains in order.
+        """Rút tin nhắn kế tiếp trong hàng đợi.
+
+        Chỉ chạy khi hội thoại NÀY đang rảnh và chưa chạm trần số lượt song song
+        toàn cục. Khởi động một lượt làm ``_view_busy()`` thành True nên đúng một
+        tin được lấy mỗi vòng — hàng đợi rút theo đúng thứ tự.
+        """
         while (not self._view_busy() and len(self._active) < self._max_parallel()
                and self.composer.has_queue()):
             nxt = self.composer.pop_next()
@@ -272,6 +304,7 @@ class ChatTurnRunnerMixin:
             self._start_turn(nxt.get("text", ""), nxt.get("attachments", []))
 
     def stop(self) -> None:
+        """Dừng mọi lượt đang chạy của hội thoại này và xoá sạch hàng đợi."""
         if not self._active:
             return
         for w in list(self._active):
diff --git a/presentation/chat/composer_mime.py b/presentation/chat/composer_mime.py
new file mode 100644
index 0000000..36fd466
--- /dev/null
+++ b/presentation/chat/composer_mime.py
@@ -0,0 +1,86 @@
+"""Đọc dữ liệu dán/kéo-thả vào ô soạn tin, và nhận diện lệnh trả lời tại chỗ.
+
+Tách khỏi ``composer_widget.py`` vì hai bên đều cần: ô nhập
+(``chat_input_box.py::_Input``) bắt sự kiện dán và thả, còn ``Composer`` bọc
+ngoài quyết định tệp nào được nhận. Đợt tách widget (R08) để mấy hàm này ở lại
+trong ``composer_widget.py`` trong khi phần gọi chúng đã sang
+``chat_input_box.py`` — thành ra dán hay thả tệp vào ô chat đều ném
+``NameError`` (F-12). Đặt ở một module thứ ba là chỗ duy nhất không lặp lại
+được lỗi ấy.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from typing import List
+
+from PySide6.QtGui import QImage
+
+from ...config import CONFIG_DIR
+
+#: ``/skill`` hoặc ``/skill:<tên>`` đứng một mình — không có phần yêu cầu theo sau.
+_BARE_SKILL = re.compile(r"^/skill:[\w\-.]+$")
+
+#: ``/agent`` hoặc ``/agent:<tên>`` đứng một mình.
+_BARE_AGENT = re.compile(r"^/agent:[\w\-.]+$")
+
+
+def save_pasted_image(image) -> str | None:
+    """Ghi ảnh vừa dán/kéo vào thư mục cấu hình; trả về đường dẫn, lỗi thì ``None``.
+
+    Tên tệp lấy tới phần nghìn giây vì dán liên tiếp trong cùng một giây là
+    chuyện thường — tính tới giây thôi là ảnh sau đè ảnh trước.
+    """
+    try:
+        if not isinstance(image, QImage) or image.isNull():
+            return None
+        folder = CONFIG_DIR / "pasted"
+        folder.mkdir(parents=True, exist_ok=True)
+        name = "paste-" + datetime.now().strftime("%Y%m%d-%H%M%S-%f")[:-3] + ".png"
+        path = folder / name
+        if image.save(str(path), "PNG"):
+            return str(path)
+    except Exception:  # noqa: BLE001 — dán ảnh hỏng không đáng làm vỡ ô nhập
+        return None
+    return None
+
+
+def is_local_skill_command(text: str) -> bool:
+    """``/skill`` (liệt kê) hoặc ``/skill:<tên>`` (chọn) — lệnh trả lời ngay tại chỗ.
+
+    Những lệnh này phải chạy được cả khi đang có lượt chat chạy dở, nên chúng đi
+    thẳng chứ không vào hàng đợi. Khác với ``/skill:<tên> <yêu cầu>``: cái đó là
+    một lượt chat thật và phải xếp hàng như mọi lượt khác.
+    """
+    t = (text or "").strip()
+    return t == "/skill" or bool(_BARE_SKILL.match(t))
+
+
+def is_local_agent_command(text: str) -> bool:
+    """Như :func:`is_local_skill_command` nhưng cho lệnh ``/agent``."""
+    t = (text or "").strip()
+    return t == "/agent" or bool(_BARE_AGENT.match(t))
+
+
+def paths_from_mime(md) -> List[str]:
+    """Rút danh sách đường dẫn tệp từ dữ liệu kéo-thả/dán.
+
+    Ưu tiên đường dẫn tệp thật; chỉ khi không có tệp nào mới xét tới ảnh trong
+    bộ nhớ tạm và ghi nó ra tệp. Thứ tự này quan trọng: kéo một tệp ảnh từ
+    Explorer thì dữ liệu mang CẢ đường dẫn lẫn ảnh xem trước, và ta muốn tệp
+    gốc chứ không muốn một bản sao PNG.
+    """
+    paths: List[str] = []
+    if md.hasUrls():
+        for u in md.urls():
+            if u.isLocalFile():
+                paths.append(u.toLocalFile())
+    if not paths and md.hasImage():
+        p = save_pasted_image(md.imageData())
+        if p:
+            paths.append(p)
+    return paths
+
+
+__all__ = ["paths_from_mime", "save_pasted_image",
+           "is_local_skill_command", "is_local_agent_command"]
diff --git a/presentation/chat/composer_widget.py b/presentation/chat/composer_widget.py
index 74c3eb7..43829d1 100644
--- a/presentation/chat/composer_widget.py
+++ b/presentation/chat/composer_widget.py
@@ -7,77 +7,28 @@ turns finish and free up a slot. Files/images can be attached to a message.
 """
 from __future__ import annotations
 
-from .chat_input_box import _Input, _SkillPopup
-
-from datetime import datetime
 from pathlib import Path
 from typing import Dict, List
 
 from PySide6.QtCore import Qt, Signal
-from PySide6.QtGui import QImage, QKeyEvent
 from PySide6.QtWidgets import (
     QFileDialog, QHBoxLayout, QLabel, QListView, QListWidget, QListWidgetItem,
-    QPlainTextEdit, QPushButton, QVBoxLayout, QWidget,
+    QPushButton, QVBoxLayout, QWidget,
 )
 
-from ...config import CONFIG_DIR
 from ...i18n import on_language_changed, tr
 from ...theme import current_palette
 from ...ui.icons import icon, IconLabel
-
-
-def _save_pasted_image(image) -> str | None:
-    """Save a clipboard/drag QImage to the config dir; return its path."""
-    try:
-        if not isinstance(image, QImage) or image.isNull():
-            return None
-        folder = CONFIG_DIR / "pasted"
-        folder.mkdir(parents=True, exist_ok=True)
-        name = "paste-" + datetime.now().strftime("%Y%m%d-%H%M%S-%f")[:-3] + ".png"
-        path = folder / name
-        if image.save(str(path), "PNG"):
-            return str(path)
-    except Exception:
-        return None
-    return None
-
-
-def _is_local_skill_command(text: str) -> bool:
-    """True for a bare ``/skill`` (list) or ``/skill:<name>`` (select) command that
-    is answered inline instantly — these must run even while a turn is busy, so they
-    bypass the message queue (unlike ``/skill:<name> <request>``, which is a real
-    turn and should queue)."""
-    import re
-    t = (text or "").strip()
-    return t == "/skill" or bool(re.match(r"^/skill:[\w\-.]+$", t))
-
-
-def _is_local_agent_command(text: str) -> bool:
-    """Same as ``_is_local_skill_command`` but for the ``/agent`` directive: a bare
-    ``/agent`` (list) or ``/agent:<name>`` (select) is answered inline instantly."""
-    import re
-    t = (text or "").strip()
-    return t == "/agent" or bool(re.match(r"^/agent:[\w\-.]+$", t))
-
-
-def _paths_from_mime(md) -> List[str]:
-    paths: List[str] = []
-    if md.hasUrls():
-        for u in md.urls():
-            if u.isLocalFile():
-                paths.append(u.toLocalFile())
-    if not paths and md.hasImage():
-        p = _save_pasted_image(md.imageData())
-        if p:
-            paths.append(p)
-    return paths
-
-
-
-
+from .chat_input_box import _Input
+from .composer_mime import is_local_agent_command, is_local_skill_command
 
 
 class Composer(QWidget):
+    """Vùng soạn tin: ô nhập, tệp đính kèm, hàng đợi tin nhắn và dải trạng thái.
+
+    Hàng đợi cho phép gõ tiếp trong lúc lượt trước còn chạy — chỗ gọi rút dần
+    qua :meth:`pop_next` sau mỗi lượt xong.
+    """
     submitted = Signal(str, list)        # (text, attachment paths)
     stop_requested = Signal()
     queue_changed = Signal(int)
@@ -87,6 +38,11 @@ class Composer(QWidget):
     manage_skills = Signal()             # relayed from the /skill popup "Manage skills…"
 
     def __init__(self, placeholder_key: str = "composer.placeholder_default"):
+        """Dựng ô soạn kèm hàng đính kèm và hàng đợi tin nhắn.
+
+        Người dùng gõ tiếp trong lúc lượt trước đang chạy thì tin mới vào hàng đợi
+        chứ không bị bỏ.
+        """
         super().__init__()
         self._placeholder_key = placeholder_key   # i18n key, re-looked-up on language change
         self._queue: List[Dict] = []          # each: {"text": str, "attachments": [str]}
@@ -182,6 +138,7 @@ class Composer(QWidget):
         on_language_changed(self._retranslate)
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho placeholder và các tooltip."""
         self.queue_list.setToolTip(tr("composer.queue_tooltip"))
         self.attach_list.setToolTip(tr("composer.attachments_tooltip"))
         self.attach_btn.setToolTip(tr("composer.attach_btn_tooltip"))
@@ -193,6 +150,9 @@ class Composer(QWidget):
         self._refresh_attachments()
 
     def add_bottom_right(self, widget) -> None:
+        """Gắn thêm một widget vào dải trạng thái dưới ô nhập (bộ chọn agent, định
+        tuyến, usage…).
+        """
         self.extra_row.addWidget(widget)
 
     def add_bottom_left(self, widget) -> None:
@@ -205,6 +165,7 @@ class Composer(QWidget):
 
     # ---- public API --------------------------------------------------
     def set_text(self, text: str) -> None:
+        """Đặt nội dung ô nhập và đưa con trỏ vào đó."""
         self.input.setPlainText(text)
         self.input.setFocus()
 
@@ -228,9 +189,11 @@ class Composer(QWidget):
         self.stop_btn.setVisible(running)
 
     def has_queue(self) -> bool:
+        """Còn tin nhắn nào đang xếp hàng chờ gửi không."""
         return bool(self._queue)
 
     def pop_next(self) -> Dict | None:
+        """Lấy tin nhắn kế tiếp trong hàng đợi ra; ``None`` nếu hàng đợi rỗng."""
         if not self._queue:
             return None
         item = self._queue.pop(0)
@@ -238,15 +201,18 @@ class Composer(QWidget):
         return item
 
     def clear_queue(self) -> None:
+        """Xoá sạch hàng đợi (dùng khi người dùng bấm Dừng)."""
         self._queue.clear()
         self._refresh_queue()
 
     def enqueue(self, text: str, attachments: List[str] | None = None) -> None:
+        """Xếp một tin nhắn vào cuối hàng đợi."""
         self._queue.append({"text": text, "attachments": list(attachments or [])})
         self._refresh_queue()
 
     # ---- attachments -------------------------------------------------
     def set_max_attachments(self, n: int) -> None:
+        """Đặt trần số tệp đính kèm cho một tin nhắn."""
         self._max_attachments = max(0, int(n or 0))
 
     def _add_one(self, path: str) -> bool:
@@ -261,6 +227,7 @@ class Composer(QWidget):
         return True
 
     def _pick_attachments(self) -> None:
+        """Mở hộp thoại chọn tệp đính kèm."""
         files, _ = QFileDialog.getOpenFileNames(
             self, tr("composer.attach_dialog_title"), "",
             tr("composer.attach_dialog_filter"),
@@ -281,6 +248,7 @@ class Composer(QWidget):
             self.input.setPlaceholderText(tr("chatpanel.attached_hint", names=names))
 
     def _remove_attachment(self, item: QListWidgetItem) -> None:
+        """Gỡ một tệp đính kèm khỏi danh sách."""
         idx = self.attach_list.row(item)
         if 0 <= idx < len(self._attachments):
             self._remove_attachment_path(self._attachments[idx])
@@ -293,6 +261,7 @@ class Composer(QWidget):
             self.attachment_removed.emit(path)   # also drop it from the Input panel
 
     def _refresh_attachments(self) -> None:
+        """Vẽ lại danh sách tệp đính kèm."""
         self.attach_list.clear()
         for p in self._attachments:
             item = QListWidgetItem()
@@ -328,6 +297,10 @@ class Composer(QWidget):
 
     # ---- submit / queue ----------------------------------------------
     def _on_submit(self) -> None:
+        """Gửi tin: bận thì xếp hàng, rảnh thì phát ``submitted``.
+
+        Không gửi khi vừa trống chữ vừa không có tệp đính kèm.
+        """
         text = self.input.toPlainText().strip()
         attachments = list(self._attachments)
         if not text and not attachments:
@@ -338,19 +311,21 @@ class Composer(QWidget):
         self.input.setPlaceholderText(tr(self._placeholder_key))   # clear any "Attached: …" hint
         # A local /skill or /agent list/select command is answered inline instantly
         # — run it now even while a turn is busy (don't bury it in the queue).
-        if self._busy and not (_is_local_skill_command(text) or _is_local_agent_command(text)):
+        if self._busy and not (is_local_skill_command(text) or is_local_agent_command(text)):
             self._queue.append({"text": text, "attachments": attachments})
             self._refresh_queue()
         else:
             self.submitted.emit(text, attachments)
 
     def _remove_queue_item(self, item: QListWidgetItem) -> None:
+        """Gỡ một tin khỏi hàng đợi trước khi nó được gửi."""
         idx = self.queue_list.row(item)
         if 0 <= idx < len(self._queue):
             self._queue.pop(idx)
             self._refresh_queue()
 
     def _refresh_queue(self) -> None:
+        """Vẽ lại danh sách hàng đợi và báo số lượng ra ngoài."""
         self.queue_list.clear()
         for i, entry in enumerate(self._queue, 1):
             text = entry.get("text", "")
diff --git a/presentation/co4e/agent_list_panel.py b/presentation/co4e/agent_list_panel.py
index b172223..508b565 100644
--- a/presentation/co4e/agent_list_panel.py
+++ b/presentation/co4e/agent_list_panel.py
@@ -53,6 +53,7 @@ class AgentListPanel(QWidget):
     """
 
     def __init__(self, parent: QWidget | None = None) -> None:
+        """Danh sách agent ở cột trái Co4E Studio, kèm nút tạo mới."""
         super().__init__(parent)
         self.new_btn = QPushButton(tr("co4e.new"))
         self.new_btn.setIcon(icon("plus"))
diff --git a/presentation/co4e/canvas_geometry.py b/presentation/co4e/canvas_geometry.py
index 87f0918..855f8d5 100644
--- a/presentation/co4e/canvas_geometry.py
+++ b/presentation/co4e/canvas_geometry.py
@@ -28,10 +28,15 @@ _CORNER_R = 12             # edge elbow corner radius
 
 
 def _dist(a: QPointF, b: QPointF) -> float:
+    """Khoảng cách Euclid giữa hai điểm."""
     return ((a.x() - b.x()) ** 2 + (a.y() - b.y()) ** 2) ** 0.5
 
 
 def _towards(a: QPointF, b: QPointF, d: float) -> QPointF:
+    """Điểm cách ``a`` một đoạn ``d`` theo hướng đi về ``b``.
+
+    Hai điểm trùng nhau thì trả về chính ``a``, tránh chia cho 0.
+    """
     dist = _dist(a, b)
     if dist < 1e-6:
         return QPointF(a)
@@ -74,6 +79,10 @@ def _seg_hits_rect(p1: QPointF, p2: QPointF, rect: QRectF) -> bool:
 
 
 def _hits(points, obstacles) -> bool:
+    """Đường gấp khúc này có cắt qua hình chữ nhật vật cản nào không.
+
+    Dùng để định tuyến đường nối lách qua các node khác.
+    """
     for i in range(len(points) - 1):
         for r in obstacles:
             if _seg_hits_rect(points[i], points[i + 1], r):
@@ -122,5 +131,8 @@ def _ortho_path(src: QPointF, dst: QPointF, r: float = _CORNER_R) -> QPainterPat
 
 
 def _elide(text: str, n: int) -> str:
+    """Cắt chuỗi cho vừa ``n`` ký tự và thay xuống dòng bằng dấu cách — nhãn trên
+    khung vẽ chỉ có một dòng.
+    """
     text = (text or "").replace("\n", " ")
     return text if len(text) <= n else text[: n - 1] + "…"
diff --git a/presentation/co4e/canvas_interaction_mixin.py b/presentation/co4e/canvas_interaction_mixin.py
index 491d0b9..75b7135 100644
--- a/presentation/co4e/canvas_interaction_mixin.py
+++ b/presentation/co4e/canvas_interaction_mixin.py
@@ -49,6 +49,11 @@ class _CanvasInteractionMixin:
 
     # ---- bottom-left overlay (zoom / fit) --------------------------------
     def add_overlay(self, widget) -> None:
+        """Gắn thanh điều khiển zoom/fit vào góc dưới-trái khung nhìn.
+
+        Widget được đặt làm con của ``viewport()`` chứ không của khung vẽ, nên nó
+        đứng yên khi người dùng kéo hay phóng to đồ thị.
+        """
         self._overlay = widget
         widget.setParent(self.viewport())
         widget.show()
@@ -56,6 +61,7 @@ class _CanvasInteractionMixin:
         self._place_overlay()
 
     def _place_overlay(self) -> None:
+        """Ghim lại thanh điều khiển vào góc dưới-trái, cách lề 12px."""
         if self._overlay is not None:
             self._overlay.adjustSize()
             vp = self.viewport()
@@ -63,10 +69,16 @@ class _CanvasInteractionMixin:
             self._overlay.raise_()
 
     def resizeEvent(self, e):  # noqa: N802
+        """Đổi kích thước khung thì ghim lại thanh điều khiển."""
         super().resizeEvent(e)
         self._place_overlay()
 
     def scrollContentsBy(self, dx, dy):  # noqa: N802
+        """Cuộn khung thì ghim lại thanh điều khiển.
+
+        ``QGraphicsView`` cuộn cả widget con của viewport theo cảnh, nên không
+        ghim lại thì nút +/−/fit sẽ trôi khỏi góc.
+        """
         # QGraphicsView scrolls the viewport's child widgets along with the
         # scene, so panning/scrolling would drag the zoom overlay off-corner.
         # Re-pin it after every scroll so +/−/fit stay fixed in place.
@@ -74,11 +86,19 @@ class _CanvasInteractionMixin:
         self._place_overlay()
 
     def showEvent(self, e):  # noqa: N802
+        """Lần hiện đầu tiên mới biết kích thước thật của viewport — ghim lại lúc đó."""
         super().showEvent(e)
         self._place_overlay()   # viewport size is final once shown
 
     # ---- zoom / fit -------------------------------------------------------
     def _zoom_by(self, factor: float) -> None:
+        """Phóng to/thu nhỏ theo hệ số, chặn trong khoảng ``_ZOOM_MIN``..``_ZOOM_MAX``.
+
+        Mức phóng hiện tại đọc thẳng từ ma trận biến đổi, KHÔNG dùng biến đếm
+        riêng: biến đếm lệch khỏi thực tế sau mỗi lần ``fit_view``/``relayout``/
+        ``reset_zoom`` là đúng thứ từng làm nút +/− và Ctrl+lăn ngẫu nhiên chết.
+        Chặn ở đích rồi mới tính hệ số cần áp, nên vẫn phóng được sát mép giới hạn.
+        """
         # Derive the CURRENT scale from the live transform (never a separate
         # accumulator that can drift out of sync with fit_view/relayout/reset —
         # that drift is what made the +/− buttons and Ctrl+wheel randomly stop
@@ -92,16 +112,22 @@ class _CanvasInteractionMixin:
         self._zoom = target
 
     def zoom_in(self) -> None:
+        """Phóng to một nấc (×1,15)."""
         self._zoom_by(1.15)
 
     def zoom_out(self) -> None:
+        """Thu nhỏ một nấc (÷1,15)."""
         self._zoom_by(1 / 1.15)
 
     def reset_zoom(self) -> None:
+        """Về đúng tỉ lệ 1:1 và bỏ mọi dịch chuyển."""
         self.resetTransform()
         self._zoom = 1.0
 
     def wheelEvent(self, e):
+        """Lăn chuột: Ctrl = phóng to/thu nhỏ quanh con trỏ, Shift = cuộn ngang,
+        không phím = cuộn dọc như mặc định.
+        """
         # Ctrl+wheel = zoom (anchored under the cursor); Shift+wheel = pan
         # horizontally; plain wheel scrolls vertically.
         if e.modifiers() & Qt.ControlModifier:
@@ -117,6 +143,7 @@ class _CanvasInteractionMixin:
 
     # ---- middle-mouse drag-to-pan ----------------------------------------
     def mousePressEvent(self, e):
+        """Nhấn chuột giữa: bắt đầu kéo cả khung (pan), đổi con trỏ thành bàn tay nắm."""
         if e.button() == Qt.MiddleButton:
             self._panning = True
             self._pan_start = e.position().toPoint()
@@ -126,6 +153,7 @@ class _CanvasInteractionMixin:
         super().mousePressEvent(e)
 
     def mouseMoveEvent(self, e):
+        """Đang kéo khung: dời hai thanh cuộn ngược chiều con trỏ."""
         if self._panning and self._pan_start is not None:
             pos = e.position().toPoint()
             delta = pos - self._pan_start
@@ -137,6 +165,7 @@ class _CanvasInteractionMixin:
         super().mouseMoveEvent(e)
 
     def mouseReleaseEvent(self, e):
+        """Thả chuột giữa: kết thúc kéo khung, trả con trỏ về bình thường."""
         if e.button() == Qt.MiddleButton and self._panning:
             self._panning = False
             self.setCursor(Qt.ArrowCursor)
@@ -208,6 +237,9 @@ class _CanvasInteractionMixin:
 
     # ---- key / drop -------------------------------------------------------
     def keyPressEvent(self, e):
+        """Phím tắt: Delete/Backspace xoá phần đang chọn, Esc huỷ lượt nối đang dở,
+        Ctrl +/−/0 phóng to/thu nhỏ/về 1:1.
+        """
         if e.key() in (Qt.Key_Delete, Qt.Key_Backspace):
             self.delete_selected()
             return
@@ -227,18 +259,25 @@ class _CanvasInteractionMixin:
         super().keyPressEvent(e)
 
     def dragEnterEvent(self, e):
+        """Chỉ nhận thứ kéo vào mang đúng định dạng của bảng nguyên liệu Co4E."""
         if e.mimeData().hasFormat(CO4E_MIME):
             e.acceptProposedAction()
         else:
             super().dragEnterEvent(e)
 
     def dragMoveEvent(self, e):
+        """Giữ trạng thái nhận thả trong suốt lúc rê qua khung."""
         if e.mimeData().hasFormat(CO4E_MIME):
             e.acceptProposedAction()
         else:
             super().dragMoveEvent(e)
 
     def dropEvent(self, e):
+        """Thả một bước hoặc cả một luồng từ bảng nguyên liệu xuống đúng vị trí con trỏ.
+
+        Payload hỏng thì bỏ qua lặng lẽ — thả nhầm thứ gì đó vào khung không
+        được phép làm vỡ màn hình.
+        """
         if not e.mimeData().hasFormat(CO4E_MIME):
             super().dropEvent(e)
             return
diff --git a/presentation/co4e/canvas_items.py b/presentation/co4e/canvas_items.py
index 04893e7..079f441 100644
--- a/presentation/co4e/canvas_items.py
+++ b/presentation/co4e/canvas_items.py
@@ -58,6 +58,9 @@ class _NodeItem(QGraphicsObject):
     """One draggable step card. Emits signals via the parent canvas."""
 
     def __init__(self, node: Node, canvas: "Co4ECanvas"):
+        """Thẻ một bước trên khung vẽ: kéo được, chọn được, và báo cho khung vẽ mỗi khi
+        nó đổi vị trí để đường nối vẽ lại theo.
+        """
         super().__init__()
         self.node = node
         self.canvas = canvas
@@ -70,13 +73,22 @@ class _NodeItem(QGraphicsObject):
         self.setZValue(2)
 
     def boundingRect(self) -> QRectF:
+        """Khung bao của node, nới rộng hai bên cho hai cổng vào/ra vẽ trọn vẹn."""
         # slack left/right so the input/output ports (now on the sides) paint cleanly
         return QRectF(-_PORT_R - 2, -3, _NODE_W + 2 * _PORT_R + 4, _NODE_H + 6)
 
     def _card_rect(self) -> QRectF:
+        """Khung thẻ (đã trừ 1px viền) — phần thân thật sự được vẽ."""
         return QRectF(1, 1, _NODE_W - 2, _NODE_H - 2)
 
     def paint(self, p, _opt, _widget=None):
+        """Vẽ thẻ bước: viền, dải tiêu đề, nhãn, vai trò, xem trước nội dung, chân thẻ và hai cổng.
+
+        Dải tiêu đề dùng màu trạng thái đã pha loãng (alpha 48) chứ không dùng
+        nguyên màu — để chữ trên thẻ vẫn là thứ nổi nhất. Cổng vào (trái) rỗng
+        ruột, cổng ra (phải) đặc ruột: cổng đặc chính là tay nắm để kéo nối sang
+        bước sau, nên nó phải trông "cầm được".
+        """
         tok = current_palette()
         step = self.node.data
         accent = QColor(_status_color(self.status))
@@ -137,10 +149,21 @@ class _NodeItem(QGraphicsObject):
         p.drawEllipse(QPointF(_NODE_W - 1, _NODE_H / 2), _PORT_R, _PORT_R)
 
     def _in_out_port(self, pos: QPointF) -> bool:
+        """Điểm ``pos`` có nằm trong vùng bắt của cổng ra không.
+
+        Vùng bắt (``_PORT_HIT``) rộng hơn hình vẽ để chuột không cần trúng đúng
+        chấm tròn nhỏ mới kéo được.
+        """
         d = pos - QPointF(_NODE_W, _NODE_H / 2)
         return (d.x() * d.x() + d.y() * d.y()) ** 0.5 <= _PORT_HIT
 
     def itemChange(self, change, value):
+        """Đồng bộ vị trí node về dữ liệu, và đưa node đang chọn lên trên.
+
+        Kéo node xong phải ghi lại toạ độ vào ``self.node`` rồi vẽ lại đường nối,
+        nếu không lần lưu kế tiếp sẽ ghi toạ độ cũ. Node được chọn nhảy lên
+        z=4 (trên cả cạnh ở z=3) để không bị đường nối che lúc đang sửa.
+        """
         if change == QGraphicsItem.ItemPositionHasChanged:
             self.node.x = float(self.pos().x())
             self.node.y = float(self.pos().y())
@@ -154,11 +177,17 @@ class _NodeItem(QGraphicsObject):
         return super().itemChange(change, value)
 
     def hoverMoveEvent(self, e):
+        """Đổi con trỏ thành bàn tay khi rê qua cổng ra — gợi ý là kéo nối được."""
         # a hand cursor over the output port hints it's draggable-to-connect
         self.setCursor(Qt.PointingHandCursor if self._in_out_port(e.pos()) else Qt.ArrowCursor)
         super().hoverMoveEvent(e)
 
     def mousePressEvent(self, e):
+        """Bấm chuột: chốt lượt nối đang chờ, hoặc bắt đầu kéo nối từ cổng ra.
+
+        Thứ tự quan trọng: đang có lượt nối chờ (mở từ menu chuột phải) thì cú
+        bấm này là chọn đích, không phải chọn node.
+        """
         if self.canvas._connect_from is not None:
             self.canvas._finish_connect(self.node.id)
             e.accept()
@@ -172,6 +201,7 @@ class _NodeItem(QGraphicsObject):
         super().mousePressEvent(e)
 
     def mouseMoveEvent(self, e):
+        """Rê chuột trong lúc kéo nối: vẽ lại đường nét đứt theo con trỏ."""
         if self._porting:
             self.canvas.update_port_drag(self.mapToScene(e.pos()))
             e.accept()
@@ -179,6 +209,7 @@ class _NodeItem(QGraphicsObject):
         super().mouseMoveEvent(e)
 
     def mouseReleaseEvent(self, e):
+        """Thả chuột: kết thúc lượt kéo nối (nối cạnh nếu rơi trúng node khác)."""
         if self._porting:
             self._porting = False
             self.canvas.finish_port_drag(self.mapToScene(e.pos()))
@@ -187,10 +218,12 @@ class _NodeItem(QGraphicsObject):
         super().mouseReleaseEvent(e)
 
     def mouseDoubleClickEvent(self, e):
+        """Bấm đúp một bước: báo lên để mở bảng thuộc tính của bước đó."""
         self.canvas.node_activated.emit(self.node.id)
         e.accept()
 
     def contextMenuEvent(self, e):
+        """Menu chuột phải trên node: thêm bước kế, nối từ đây, xoá bước."""
         menu = QMenu()
         a_add = menu.addAction("＋ Add next step")
         a_conn = menu.addAction("→ Connect from here")
@@ -205,11 +238,22 @@ class _NodeItem(QGraphicsObject):
         e.accept()
 
     def center(self) -> QPointF:
+        """Toạ độ tâm node trên khung — dùng để định tuyến đường nối."""
         return self.pos() + QPointF(_NODE_W / 2, _NODE_H / 2)
 
 
 class _EdgeItem(QGraphicsPathItem):
+    """Một đường nối giữa hai bước, kèm mũi tên ở đầu đích.
+
+    Nằm ở z=3, tức trên thẻ bước (z=2), để đường nối không bao giờ bị thẻ
+    che khuất — node đang được chọn thì tự nhảy lên z=4.
+    """
     def __init__(self, edge: Edge, canvas: "Co4ECanvas"):
+        """Đường nối giữa hai bước.
+
+        Đặt ``z=3``, trên thẻ bước (``z=2``): đường nối bị thẻ che thì không nhìn ra
+        luồng chạy nữa.
+        """
         super().__init__()
         self.edge = edge
         self.canvas = canvas
@@ -223,6 +267,7 @@ class _EdgeItem(QGraphicsPathItem):
         self._apply_pen()
 
     def _apply_pen(self):
+        """Chọn màu và độ dày nét theo trạng thái: đang chọn > đang rê chuột > bình thường."""
         tok = current_palette()
         if self.isSelected():
             color, w = QColor(tok.accent), 3
@@ -233,13 +278,20 @@ class _EdgeItem(QGraphicsPathItem):
         self.setPen(QPen(color, w, Qt.SolidLine, Qt.RoundCap, Qt.RoundJoin))
 
     def update_path(self, points):
+        """Vẽ lại đường theo danh sách điểm đã định tuyến, nhớ lại điểm cuối để đặt mũi tên."""
         self._dst = points[-1] if points else None
         self.setPath(_rounded_path(points))
 
     def boundingRect(self):
+        """Khung bao của đường, nới thêm 10px mỗi phía cho mũi tên."""
         return super().boundingRect().adjusted(-10, -10, 10, 10)   # room for the arrowhead
 
     def shape(self):
+        """Nới vùng bấm/chọn lên 14px.
+
+        Đường nối chỉ dày 2px — không nới thì gần như không thể trỏ trúng để
+        chọn hay mở menu xoá.
+        """
         # Widen the clickable/selectable area so a thin line is easy to grab.
         from PySide6.QtGui import QPainterPathStroker
         stroker = QPainterPathStroker()
@@ -247,18 +299,21 @@ class _EdgeItem(QGraphicsPathItem):
         return stroker.createStroke(self.path())
 
     def hoverEnterEvent(self, e):
+        """Rê chuột vào: làm nét đậm lên để thấy rõ đang trỏ vào đường nào."""
         self._hover = True
         self._apply_pen()
         self.update()
         super().hoverEnterEvent(e)
 
     def hoverLeaveEvent(self, e):
+        """Rời chuột: trả nét về trạng thái bình thường."""
         self._hover = False
         self._apply_pen()
         self.update()
         super().hoverLeaveEvent(e)
 
     def paint(self, p, opt, widget=None):
+        """Vẽ đường nối và mũi tên tam giác chĩa vào cổng vào của node đích."""
         self._apply_pen()
         super().paint(p, opt, widget)
         # arrowhead at the target, pointing right into its (left) input port
@@ -277,6 +332,7 @@ class _EdgeItem(QGraphicsPathItem):
             p.drawPolygon(tri)
 
     def contextMenuEvent(self, e):
+        """Menu chuột phải trên đường nối: xoá liên kết."""
         menu = QMenu()
         act_del = menu.addAction("🗑 Delete connection")
         if menu.exec(e.screenPos()) is act_del:
diff --git a/presentation/co4e/co4e_agents.py b/presentation/co4e/co4e_agents.py
index 5cb5f91..32c14e1 100644
--- a/presentation/co4e/co4e_agents.py
+++ b/presentation/co4e/co4e_agents.py
@@ -11,9 +11,12 @@ from ...presentation.co4e.co4e_chat_view import _skill_names
 
 
 class Co4EAgentsMixin:
+    """Quản lý agent tự tạo và thư viện skill dùng trong luồng Co4E."""
     def _new_agent(self) -> None:
+        """Mở hộp thoại tạo agent tự tạo mới."""
         self._edit_agent_dialog(co4e.new_custom_agent(""))
     def _edit_agent(self) -> None:
+        """Sửa agent đang chọn; chưa chọn gì thì nhắc người dùng chọn."""
         item = self.agent_list.currentItem()
         cid = item.data(Qt.UserRole + 1) if item else None
         if not cid:
@@ -23,6 +26,7 @@ class Co4EAgentsMixin:
         if agent is not None:
             self._edit_agent_dialog(agent)
     def _edit_agent_dialog(self, agent: co4e.CustomAgent) -> None:
+        """Mở hộp thoại sửa agent; bấm OK thì lưu và nạp lại cột bên trái."""
         from ...ui.co4e_agent_dialog import Co4EAgentDialog
 
         dlg = Co4EAgentDialog(self.ctx, agent, _skill_names(), self)
@@ -30,6 +34,7 @@ class Co4EAgentsMixin:
             co4e.save_custom_agent(dlg.result_agent())
             self._reload_sidebar()
     def _delete_agent(self) -> None:
+        """Xoá agent đang chọn; chưa chọn gì thì nhắc người dùng chọn."""
         item = self.agent_list.currentItem()
         cid = item.data(Qt.UserRole + 1) if item else None
         if not cid:
@@ -38,11 +43,16 @@ class Co4EAgentsMixin:
         co4e.delete_custom_agent(cid)
         self._reload_sidebar()
     def _manage_skills(self) -> None:
+        """Mở trình quản lý Skill, đóng xong thì nạp lại cột bên trái."""
         from ...ui.skills_dialog import SkillsDialog
 
         SkillsDialog(self, self.ctx).exec()
         self._reload_sidebar()
     def _skill_map(self) -> Dict[str, str]:
+        """Bảng ``{tên skill: nội dung chỉ dẫn}`` để truyền cho một lượt chạy luồng.
+
+        Cắt bỏ dòng tiêu đề của khối chỉ dẫn, chỉ giữ phần nội dung.
+        """
         out = {}
         for name in _skill_names():
             block = skills_mod.skill_prefix_for(name)
diff --git a/presentation/co4e/co4e_canvas_widget.py b/presentation/co4e/co4e_canvas_widget.py
index fd91376..2d0c896 100644
--- a/presentation/co4e/co4e_canvas_widget.py
+++ b/presentation/co4e/co4e_canvas_widget.py
@@ -44,6 +44,16 @@ __all__ = ["Co4ECanvas", "CO4E_MIME"]
 
 
 class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
+    """Khung vẽ luồng Co4E: node là bước, cạnh là thứ tự chạy.
+
+    Lớp này giữ *dữ liệu đồ thị* (thêm/xoá node, nối cạnh, định tuyến đường
+    nối). Phần thao tác chuột/bàn phím — phóng to, kéo màn, kéo-thả từ bảng
+    nguyên liệu — nằm ở ``_CanvasInteractionMixin`` để file này không vượt
+    hạn mức 400 dòng.
+
+    Mọi thay đổi làm đồ thị khác đi đều phát ``graph_changed`` để lớp trên
+    tự lưu.
+    """
     node_selected = Signal(str)     # a node was clicked (→ config panel)
     node_activated = Signal(str)    # double-clicked
     graph_changed = Signal()        # nodes/edges/positions changed (autosave)
@@ -51,6 +61,7 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
     _ZOOM_MIN, _ZOOM_MAX = 0.3, 3.0
 
     def __init__(self):
+        """Khung vẽ workflow: kéo chọn theo vùng, thu phóng lấy con trỏ làm tâm."""
         super().__init__()
         self.setObjectName("co4eCanvas")   # themed frame (see theme.py)
         self._scene = QGraphicsScene(self)
@@ -73,6 +84,12 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
 
     # ---- load / serialize -------------------------------------------------
     def load(self, nodes, edges) -> None:
+        """Nạp lại toàn bộ đồ thị, xoá sạch khung cũ.
+
+        Cạnh trỏ tới node không tồn tại thì bỏ lặng lẽ — file luồng sửa tay
+        hoặc luồng cũ có thể còn cạnh mồ côi, và treo cả màn vì một cạnh hỏng
+        thì tệ hơn là bỏ nó đi.
+        """
         self._scene.clear()
         self._nodes.clear()
         self._edges.clear()
@@ -89,14 +106,22 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         self._reposition_edges()
 
     def nodes(self):
+        """Danh sách node (dạng dữ liệu, không phải item đồ hoạ) để đem đi lưu."""
         return [it.node for it in self._nodes.values()]
 
     def edges(self):
+        """Danh sách cạnh (dạng dữ liệu) để đem đi lưu."""
         return [it.edge for it in self._edges]
 
     # ---- mutation ---------------------------------------------------------
     def add_node(self, step: Step, x: float = 60.0, y: float = 60.0,
                  connect_from: str = "") -> str:
+        """Thêm một bước vào khung và trả về id node vừa tạo.
+
+        ``connect_from`` trỏ tới node nào thì nối luôn một cạnh từ đó sang; id
+        không tồn tại thì bỏ qua phần nối. Node mới luôn được chọn ngay để bảng
+        thuộc tính bên phải mở đúng bước vừa thêm.
+        """
         node = Node(id=new_node_id(), x=x, y=y, data=step)
         item = _NodeItem(node, self)
         self._nodes[node.id] = item
@@ -123,13 +148,24 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         return tails[-1] if tails else (next(reversed(self._nodes), "") if self._nodes else "")
 
     def add_palette_step(self, step: Step, pos: QPointF) -> None:
+        """Thả một bước từ bảng nguyên liệu xuống đúng vị trí con trỏ.
+
+        Tự nối vào đuôi chuỗi hiện có, để kéo liên tiếp vài bước là thành một
+        luồng chạy được mà không phải nối tay từng cạnh.
+        """
         tail = self._chain_tail()
         self.add_node(step, x=pos.x(), y=pos.y(), connect_from=tail)
 
     def begin_connect(self, source_id: str) -> None:
+        """Bắt đầu nối cạnh bằng menu chuột phải: ghi nhớ node nguồn."""
         self._connect_from = source_id
 
     def _finish_connect(self, target_id: str) -> None:
+        """Kết thúc lượt nối bằng menu: tạo cạnh và xoá trạng thái đang nối.
+
+        Tự nối vào chính mình thì không tạo cạnh, nhưng vẫn xoá trạng thái —
+        nếu không, lần bấm kế tiếp sẽ nối nhầm từ node cũ.
+        """
         src = self._connect_from
         self._connect_from = None
         if src and src != target_id:
@@ -137,6 +173,7 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
 
     # ---- manual drag-to-connect (from a node's output port) ---------------
     def begin_port_drag(self, source_id: str, scene_pt: QPointF) -> None:
+        """Bắt đầu kéo cạnh từ cổng ra của một node: dựng đường nét đứt tạm."""
         self._port_src = source_id
         self._port_src_pt = scene_pt
         self._temp_edge = QGraphicsPathItem()
@@ -146,11 +183,17 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         self._scene.addItem(self._temp_edge)
 
     def update_port_drag(self, scene_pt: QPointF) -> None:
+        """Vẽ lại đường nét đứt theo con trỏ trong lúc kéo."""
         if self._temp_edge is None or self._port_src_pt is None:
             return
         self._temp_edge.setPath(_ortho_path(self._port_src_pt, scene_pt))
 
     def finish_port_drag(self, scene_pt: QPointF) -> None:
+        """Thả chuột: nối cạnh nếu rơi trúng một node khác, và luôn dọn đường tạm.
+
+        Thả vào chỗ trống hay vào chính node nguồn đều không tạo cạnh — nhưng
+        trạng thái kéo vẫn phải được xoá, nếu không đường nét đứt sẽ dính lại.
+        """
         src = self._port_src
         if self._temp_edge is not None:
             self._scene.removeItem(self._temp_edge)
@@ -162,12 +205,18 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
             self._make_edge(src, tgt)
 
     def _node_at(self, scene_pt: QPointF) -> Optional[str]:
+        """Id node nằm dưới một điểm trên khung; ``None`` nếu là chỗ trống."""
         for it in self._scene.items(scene_pt):
             if isinstance(it, _NodeItem):
                 return it.node.id
         return None
 
     def _make_edge(self, source: str, target: str) -> None:
+        """Tạo cạnh nguồn → đích.
+
+        Bỏ qua cạnh tự nối và cạnh trùng cặp đã có — kéo hai lần cùng một
+        hướng không được sinh ra hai đường chồng lên nhau.
+        """
         if source == target:
             return
         if any(e.edge.source == source and e.edge.target == target for e in self._edges):
@@ -178,11 +227,15 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         self.graph_changed.emit()
 
     def _add_edge_item(self, edge: Edge) -> None:
+        """Đưa một cạnh vào khung vẽ và vào danh sách quản lý."""
         item = _EdgeItem(edge, self)
         self._edges.append(item)
         self._scene.addItem(item)
 
     def delete_edge(self, edge: Edge) -> None:
+        """Xoá cạnh, so khớp theo cặp nguồn/đích chứ không chỉ theo danh tính đối
+        tượng — cạnh có thể đã được dựng lại sau một lần nạp.
+        """
         for e in list(self._edges):
             if e.edge is edge or (e.edge.source == edge.source and e.edge.target == edge.target):
                 self._scene.removeItem(e)
@@ -190,6 +243,7 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         self.graph_changed.emit()
 
     def delete_node(self, node_id: str) -> None:
+        """Xoá một node và mọi cạnh dính vào nó. Id không tồn tại thì bỏ qua."""
         item = self._nodes.pop(node_id, None)
         if item is None:
             return
@@ -202,23 +256,31 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         self.graph_changed.emit()
 
     def delete_selected(self) -> None:
+        """Xoá mọi node và cạnh đang được chọn.
+
+        Xoá node trước: node kéo theo cạnh của nó, nên vòng lặp cạnh phía sau
+        chỉ còn phải xử lý các cạnh được chọn riêng lẻ.
+        """
         for nid in [it.node.id for it in self._nodes.values() if it.isSelected()]:
             self.delete_node(nid)
         for e in [it.edge for it in self._edges if it.isSelected()]:
             self.delete_edge(e)
 
     def update_node_status(self, node_id: str, status: str) -> None:
+        """Đổi màu trạng thái của một node lúc luồng đang chạy (đang chạy/xong/lỗi)."""
         item = self._nodes.get(node_id)
         if item is not None:
             item.status = status
             item.update()
 
     def reset_statuses(self) -> None:
+        """Đưa mọi node về trạng thái chờ — gọi trước mỗi lần chạy lại luồng."""
         for it in self._nodes.values():
             it.status = "idle"
             it.update()
 
     def refresh_node(self, node_id: str) -> None:
+        """Vẽ lại một node sau khi nội dung bước của nó bị sửa."""
         item = self._nodes.get(node_id)
         if item is not None:
             item.update()
@@ -236,6 +298,11 @@ class Co4ECanvas(_CanvasInteractionMixin, QGraphicsView):
         return out
 
     def _reposition_edges(self) -> None:
+        """Định tuyến lại mọi đường nối.
+
+        Cạnh luôn đi từ cổng ra (giữa cạnh phải) sang cổng vào (giữa cạnh trái)
+        và lách qua các node khác, nên luồng đọc được từ trái sang phải.
+        """
         for e in self._edges:
             s = self._nodes.get(e.edge.source)
             t = self._nodes.get(e.edge.target)
diff --git a/presentation/co4e/co4e_chat.py b/presentation/co4e/co4e_chat.py
index 82e5f72..2005bae 100644
--- a/presentation/co4e/co4e_chat.py
+++ b/presentation/co4e/co4e_chat.py
@@ -20,6 +20,11 @@ from ...presentation.co4e.co4e_chat_view import ChatPanel
 
 
 class Co4EChatMixin:
+    """Khung chat của Co4E Studio: mỗi luồng có nhật ký hội thoại RIÊNG.
+
+    Hai luồng chạy song song không được trộn tin nhắn vào nhau, nên mọi thứ ở
+    đây đều lấy nhật ký qua :meth:`_active_log` thay vì dùng một biến chung.
+    """
     def _build_chat(self) -> QWidget:
         """Widget construction lives in ``ChatPanel`` (presentation/co4e/
         co4e_chat_view.py); this method just wires the panel's public
@@ -95,6 +100,7 @@ class Co4EChatMixin:
             self.chat_stack.addWidget(log)
         return log
     def _active_log(self) -> ChatView:
+        """Nhật ký hội thoại của luồng đang mở, tạo lười nếu chưa có."""
         wf = getattr(self, "_wf", None)
         return self._ensure_flow_log(wf.id if wf is not None else "__none__")
     @property
@@ -104,11 +110,18 @@ class Co4EChatMixin:
         return self._active_log()
     @property
     def _plan_bubble(self):
+        """Bong bóng kế hoạch của luồng ĐANG mở; ``None`` nếu lượt này chưa có kế hoạch.
+
+        Cất trên chính nhật ký của luồng chứ không trên mixin, để hai luồng chạy song
+        song không ghi đè kế hoạch của nhau.
+        """
         return getattr(self._active_log(), "_co4e_plan_bubble", None)
     @_plan_bubble.setter
     def _plan_bubble(self, value) -> None:
+        """Gắn bong bóng kế hoạch vào nhật ký của luồng đang mở."""
         self._active_log()._co4e_plan_bubble = value
     def _chat_send(self) -> None:
+        """Gửi tin nhắn trong khung chat Co4E; đang chạy dở thì bỏ qua."""
         text = self.chat_input.text().strip()
         if not text or self._chat_worker is not None:
             return
@@ -179,6 +192,10 @@ class Co4EChatMixin:
             self._co4e_routed_provider = None
             return ""
     def _extract_agent_directive(self, text: str):
+        """Tách lệnh ``/agent:<tên>`` khỏi câu người dùng gõ.
+
+        Trả về (tên agent, phần câu còn lại).
+        """
         m = re.search(r"(?<!\S)/agent:([\w\-.]+)", text)
         if not m:
             return "", text
@@ -186,6 +203,7 @@ class Co4EChatMixin:
         rest = (text[:m.start()] + " " + text[m.end():]).strip()
         return name, rest
     def _resolve_agent(self, name: str):
+        """Tìm agent theo slug hoặc tên, ưu tiên agent dựng sẵn rồi tới agent tự tạo."""
         low = name.lower()
         for a in BUILTIN_AGENTS:
             if a.slug == low or a.name.lower() == low:
@@ -195,6 +213,10 @@ class Co4EChatMixin:
                 return (f"You are the {ca.role} agent — {ca.name}.\n{ca.instructions}", ca.model)
         return None
     def _run_chat_turn(self, system_parts: List[str], request: str, model: str) -> None:
+        """Chạy một lượt chat ở luồng nền, ghi kết quả vào nhật ký của ĐÚNG luồng đã
+        phát lệnh — bắt giữ tham chiếu nhật ký ngay từ đầu, vì người dùng có thể
+        chuyển sang luồng khác trong lúc chờ.
+        """
         self.chat_send_btn.setEnabled(False)
         log = self.chat_log                 # THIS flow's conversation (captured)
         log._co4e_plan_bubble = None        # a fresh plan for this turn
@@ -209,6 +231,7 @@ class Co4EChatMixin:
         flow_label = wf.name if wf is not None else "flow"
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi agent Cowork và ghi nhận token đã dùng."""
             from ...core import agent_roles, usage_tracker as ut
             from ...core.chat_agent import run_cowork
             from ...core.co4e_runner import _usage_delta
@@ -220,6 +243,7 @@ class Co4EChatMixin:
             base = ut.accumulated()
 
             def _emit(ev):
+                """Chuyển tiếp sự kiện từ agent, lọc bỏ thứ khung chat này không dùng."""
                 if not isinstance(ev, dict):
                     return
                 t = ev.get("type")
@@ -240,6 +264,7 @@ class Co4EChatMixin:
             return {"text": "", "usage": usage}
 
         def on_event(ev):
+            """Vẽ dần từng mẩu trả lời vào bong bóng của lượt này."""
             if ev.get("type") == "text":
                 state["text"] += ev.get("delta", "")
                 assistant.set_markdown(state["text"])
@@ -248,6 +273,7 @@ class Co4EChatMixin:
                 self._append_plan(ev.get("steps") or [], log=log)
 
         def done(result: dict):
+            """Lượt xong: chốt nội dung cuối và mở khoá nút gửi."""
             self._chat_worker = None
             self.chat_send_btn.setEnabled(True)
             final = result.get("text") or state["text"]
@@ -256,6 +282,7 @@ class Co4EChatMixin:
             log.scroll_to_bottom()
 
         def failed(err: str):
+            """Lượt lỗi: hiện lỗi ngay trong nhật ký và mở khoá nút gửi."""
             self._chat_worker = None
             self.chat_send_btn.setEnabled(True)
             self._append_chat("error", f"[error: {err}]", log=log)
diff --git a/presentation/co4e/co4e_chat_view.py b/presentation/co4e/co4e_chat_view.py
index 366949b..d844734 100644
--- a/presentation/co4e/co4e_chat_view.py
+++ b/presentation/co4e/co4e_chat_view.py
@@ -55,6 +55,7 @@ from ...ui.routing_toggle import RoutingToggle
 
 
 def _skill_names() -> List[str]:
+    """Tên mọi skill dùng được (tự tạo + dựng sẵn); lỗi đọc thì trả list rỗng."""
     try:
         return [s.name for s in skills_mod.list_skills() + skills_mod.builtin_skills()]
     except Exception:  # noqa: BLE001
@@ -62,6 +63,7 @@ def _skill_names() -> List[str]:
 
 
 def _agent_names() -> List[str]:
+    """Tên mọi agent dùng được: agent tự tạo trước, rồi tới agent dựng sẵn chưa trùng tên."""
     names = [a.name for a in co4e.list_custom_agents()]
     names += [a.name for a in BUILTIN_AGENTS if a.name not in names]
     return names
@@ -89,6 +91,7 @@ class _ChatInput(QLineEdit):
     submit = Signal()
 
     def __init__(self, parent=None):
+        """Ô soạn của khung chat Co4E, kèm danh sách gợi ý nổi lên khi gõ lệnh."""
         super().__init__(parent)
         self._popup = QListWidget()
         self._popup.setWindowFlags(Qt.Tool | Qt.FramelessWindowHint
@@ -99,6 +102,7 @@ class _ChatInput(QLineEdit):
         self.textEdited.connect(self._maybe_popup)
 
     def _maybe_popup(self, *_a) -> None:
+        """Mở bảng gợi ý khi con trỏ đang đứng trên một lệnh ``/skill`` hoặc ``/agent``."""
         tok = _directive_token(self.text(), self.cursorPosition())
         if tok is None:
             self._popup.hide()
@@ -126,12 +130,14 @@ class _ChatInput(QLineEdit):
         self._popup.show()
 
     def _add_row(self, label: str, replacement: str, tip: str) -> None:
+        """Thêm một dòng vào bảng gợi ý, kèm chuỗi sẽ chèn và tooltip mô tả."""
         it = QListWidgetItem(label)
         it.setData(Qt.UserRole, replacement)
         it.setToolTip(tip)
         self._popup.addItem(it)
 
     def _accept(self) -> None:
+        """Chọn một mục: chèn lệnh tương ứng vào ô nhập và đóng bảng gợi ý."""
         item = self._popup.currentItem()
         self._popup.hide()
         if item is None:
@@ -147,11 +153,15 @@ class _ChatInput(QLineEdit):
         self.setFocus()
 
     def focusOutEvent(self, e):  # noqa: N802
+        """Bấm ra chỗ khác thì ẩn bảng gợi ý — trừ khi chuột đang ở trên chính bảng."""
         if not self._popup.underMouse():
             self._popup.hide()
         super().focusOutEvent(e)
 
     def keyPressEvent(self, e):  # noqa: N802
+        """Bảng gợi ý đang mở thì lên/xuống chọn mục, Enter nhận, Esc đóng;
+        không thì Enter gửi tin nhắn như bình thường.
+        """
         if self._popup.isVisible():
             k = e.key()
             n = self._popup.count()
@@ -199,6 +209,11 @@ class ChatPanel(QWidget):
     """
 
     def __init__(self, ctx) -> None:
+        """Khung chat của Co4E Studio.
+
+        Tiêu đề "Tin nhắn" nằm TRÊN hộp chat và đóng vai công tắc: bấm vào là ẩn/hiện
+        cả khối bên dưới, để lấy chỗ cho khung vẽ.
+        """
         super().__init__()
         lay = QVBoxLayout(self)
         lay.setContentsMargins(0, 0, 0, 0)
diff --git a/presentation/co4e/co4e_flow_tabs.py b/presentation/co4e/co4e_flow_tabs.py
index 1dd7132..ffe70c9 100644
--- a/presentation/co4e/co4e_flow_tabs.py
+++ b/presentation/co4e/co4e_flow_tabs.py
@@ -15,6 +15,11 @@ from ...ui.icons import icon
 
 
 class Co4EFlowTabsMixin:
+    """Dải tab kiểu trình duyệt của Co4E Studio: mỗi luồng đang mở là một tab.
+
+    Tab chỉ số 0 luôn là trang Flow Status được ghim, nên luồng thứ ``i`` nằm ở
+    tab ``i + 1`` — mọi phép đổi chỉ số trong file này đều theo quy ước đó.
+    """
     def _open_flow(self, wf: co4e.Workflow) -> None:
         """Open ``wf`` in a tab — reuse its tab if already open (like a browser),
         else add a new one and switch to it. Bar index 0 is the pinned Runs tab,
@@ -76,6 +81,11 @@ class Co4EFlowTabsMixin:
             self.flow_bar.setCurrentIndex(target)
     def _on_flow_tab_changed(self, idx: int) -> None:
         # save the outgoing flow (active_flow_idx is a FLOWS-list index) first
+        """Đổi tab: lưu luồng vừa rời đi rồi nạp luồng mới lên khung vẽ.
+
+        Phải lưu TRƯỚC khi chuyển, nếu không thay đổi chưa lưu của luồng cũ sẽ bị
+        khung vẽ ghi đè khi nạp luồng mới.
+        """
         if 0 <= self._active_flow_idx < len(self._flows) and (self._active_flow_idx + 1) != idx:
             self._sync_wf_from_canvas()
         if idx <= 0:                                   # the Runs page
@@ -111,11 +121,13 @@ class Co4EFlowTabsMixin:
         btn.clicked.connect(lambda: self._close_flow_tab_button(btn))
         self.flow_bar.setTabButton(idx, QTabBar.RightSide, btn)
     def _close_flow_tab_button(self, btn) -> None:
+        """Tìm tab ứng với nút ✕ vừa bấm rồi đóng tab đó."""
         for i in range(self.flow_bar.count()):
             if self.flow_bar.tabButton(i, QTabBar.RightSide) is btn:
                 self._close_flow_tab(i)
                 return
     def _close_flow_tab(self, idx: int) -> None:
+        """Đóng một tab luồng. Tab Flow Status (chỉ số 0) được ghim, không đóng được."""
         if idx <= 0:                                   # Runs tab is pinned
             return
         flow_idx = idx - 1
@@ -145,6 +157,7 @@ class Co4EFlowTabsMixin:
             self.flow_bar.blockSignals(False)
             self._on_flow_tab_changed(new_bar)
     def _sync_active_flow_tab_text(self) -> None:
+        """Cập nhật nhãn tab đang mở theo tên luồng; không bao giờ đổi tên tab Flow Status."""
         i = self.flow_bar.currentIndex()
         if i >= 1:                                     # never rename the Runs tab
             self.flow_bar.setTabText(i, self._wf.name or tr("co4e.untitled"))
@@ -176,5 +189,6 @@ class Co4EFlowTabsMixin:
         runs never seed each other's context)."""
         return self._flow_outputs.setdefault(wf_id, {})
     def _update_run_btn(self) -> None:
+        """Nhãn nút Chạy đổi theo trạng thái luồng đang mở: đang chạy thì thành "Dừng"."""
         self.run_btn.setText(tr("co4e.interrupt") if self._cur_run_id() is not None
                              else tr("co4e.run"))
diff --git a/presentation/co4e/co4e_layout.py b/presentation/co4e/co4e_layout.py
index 4b1607e..5e1cf28 100644
--- a/presentation/co4e/co4e_layout.py
+++ b/presentation/co4e/co4e_layout.py
@@ -22,7 +22,11 @@ from ...presentation.co4e.co4e_run_control_widget import RunsPagePanel
 
 
 class Co4ELayoutMixin:
+    """Bố cục ba cột của Co4E Studio: cột trái, khung vẽ ở giữa, bảng thuộc tính
+    bên phải — cùng dải tab luồng phía trên.
+    """
     def _build_center(self) -> QWidget:
+        """Dựng vùng giữa: dải tab luồng, khung vẽ và trang Flow Status xếp chồng."""
         from PySide6.QtWidgets import QStackedWidget, QTabBar
         page = QWidget()
         lay = QVBoxLayout(page)
@@ -235,6 +239,7 @@ class Co4ELayoutMixin:
         if narrow != self._config_collapsed:
             self._toggle_config()
     def _toggle_config(self) -> None:
+        """Gập/mở bảng thuộc tính bên phải."""
         self._config_collapsed = not self._config_collapsed
         v = self._cfg_vlayout
         if self._config_collapsed:
diff --git a/presentation/co4e/co4e_run_control_widget.py b/presentation/co4e/co4e_run_control_widget.py
index 2389eae..7a7f2a0 100644
--- a/presentation/co4e/co4e_run_control_widget.py
+++ b/presentation/co4e/co4e_run_control_widget.py
@@ -56,6 +56,11 @@ class RunsPagePanel(QWidget):
     """
 
     def __init__(self, parent: QWidget | None = None) -> None:
+        """Trang danh sách lượt chạy.
+
+        Tự mang nút quay lại vì trang này phủ kín thanh công cụ — nút đã mở nó ra
+        nằm ngoài màn hình.
+        """
         super().__init__(parent)
         v = QVBoxLayout(self)
         hdr = QHBoxLayout()
diff --git a/presentation/co4e/co4e_runs.py b/presentation/co4e/co4e_runs.py
index 25ef20a..f16b6d6 100644
--- a/presentation/co4e/co4e_runs.py
+++ b/presentation/co4e/co4e_runs.py
@@ -20,10 +20,19 @@ from ...theme import current_palette
 
 
 class Co4ERunsMixin:
+    """Phần chạy luồng của Co4E Studio: nút Chạy, ba chế độ, và bảng Flow Status.
+
+    Nhiều luồng chạy song song được, nên mọi thứ ở đây đều đánh khoá theo
+    luồng: ``_flow_runs[wf_id]`` là run của từng luồng, ``_run_logs[run_id]``
+    là nhật ký nhận sự kiện của run đó. Khung vẽ chỉ phản chiếu run của luồng
+    ĐANG hiện, còn các run khác vẫn chạy nền bình thường.
+    """
     def _current_mode(self) -> str:
+        """Chế độ chạy đang chọn: 'auto' (mặc định), 'plan' hay 'manual'."""
         return self.mode_combo.currentData() or "auto"
     def _on_mode_changed(self, *_a) -> None:
         # switching mode resets any in-progress manual sequence
+        """Đổi chế độ thì huỷ chuỗi chạy thủ công đang dở và trả nhãn nút về 'Chạy'."""
         self._manual_active = False
         self._manual_order = []
         self._manual_idx = 0
@@ -31,6 +40,11 @@ class Co4ERunsMixin:
             self.run_btn.setText(tr("co4e.run"))
     def _on_run_clicked(self) -> None:
         # THIS flow's run is active → interrupt it (other flows keep running).
+        """Bấm nút Chạy: luồng NÀY đang chạy thì dừng nó, chưa chạy thì bắt đầu theo
+        chế độ đang chọn.
+
+        Chỉ dừng run của luồng đang mở — các luồng khác không bị đụng tới.
+        """
         cur = self._cur_run_id()
         if cur is not None:
             self.manager.stop(cur)
@@ -42,6 +56,12 @@ class Co4ERunsMixin:
             self._start_canvas_run(plan_mode=(mode == "plan"))
     def _start_canvas_run(self, *, plan_mode: bool, only: Optional[set] = None,
                           seed: Optional[Dict[str, str]] = None) -> None:
+        """Bắt đầu chạy luồng trên khung vẽ.
+
+        ``only`` giới hạn ở một nhóm bước (chạy lại một nhánh); để trống thì chạy
+        cả luồng và xoá sạch trạng thái/đầu ra cũ trước. ``seed`` là đầu ra sẵn có
+        đưa vào làm ngữ cảnh, để chạy tiếp một nhánh không mất kết quả phía trên.
+        """
         self._sync_wf_from_canvas()
         if not self._wf.nodes:
             self.status_message.emit(tr("co4e.no_steps"))
@@ -65,11 +85,13 @@ class Co4ERunsMixin:
         self._start_canvas_run(plan_mode=(self._current_mode() == "plan"),
                                only={node_id}, seed=dict(self._outputs_for(self._wf.id)))
     def _run_from(self, node_id: str) -> None:
+        """Chạy lại từ một bước trở đi — tức bước đó và mọi bước phía sau nó."""
         if self._cur_run_id() is not None:
             return
         self._start_canvas_run(plan_mode=(self._current_mode() == "plan"),
                                only=self._downstream(node_id), seed=dict(self._outputs_for(self._wf.id)))
     def _downstream(self, node_id: str) -> set:
+        """Tập id các bước nằm sau ``node_id`` trên đồ thị (kể cả chính nó)."""
         adj: Dict[str, List[str]] = {}
         for e in self.canvas.edges():
             adj.setdefault(e.source, []).append(e.target)
@@ -82,6 +104,7 @@ class Co4ERunsMixin:
             stack.extend(adj.get(cur, []))
         return seen
     def _manual_run_or_advance(self) -> None:
+        """Chế độ thủ công: lần bấm đầu khởi tạo chuỗi bước, các lần sau đi tiếp một bước."""
         if not self._manual_active:
             self._sync_wf_from_canvas()
             if not self._wf.nodes:
@@ -96,6 +119,7 @@ class Co4ERunsMixin:
             self._append_chat("system", tr("co4e.manual_started", name=self._wf.name))
         self._manual_step()
     def _manual_step(self) -> None:
+        """Chạy đúng một bước trong chuỗi thủ công, hoặc kết thúc nếu đã hết bước."""
         if self._manual_idx >= len(self._manual_order):
             self._manual_active = False
             self.run_btn.setText(tr("co4e.run"))
@@ -113,6 +137,7 @@ class Co4ERunsMixin:
         self._run_logs[run_id] = self.chat_log
         self.run_btn.setText(tr("co4e.interrupt"))
     def _topo_order(self) -> List[str]:
+        """Thứ tự chạy các bước: theo lớp phụ thuộc trước, trong cùng lớp thì theo"""
         nodes = self.canvas.nodes()
         edges = self.canvas.edges()
         waves = co4e.compute_waves(nodes, edges)
@@ -122,6 +147,7 @@ class Co4ERunsMixin:
         # Per-flow routing: every run's events go to ITS OWN flow log (so parallel
         # runs never mix), and the canvas mirrors ONLY the run whose flow is the
         # one currently shown. Flow Status refreshes on its own via `changed`.
+        """Nhận sự kiện của một run và chuyển về đúng nơi."""
         h = self.manager.get(run_id)
         run_wf = h.wf_id if h is not None else None
         log = self._run_logs.get(run_id) or self.chat_log
@@ -199,6 +225,7 @@ class Co4ERunsMixin:
         box.show()
     def _refresh_runs(self) -> None:
         # Rebuild the always-fresh Runs table from the manager (single source of truth).
+        """Dựng lại bảng Flow Status từ dữ liệu của manager."""
         if not hasattr(self, "runs_table"):
             return
         p = current_palette()
@@ -241,6 +268,7 @@ class Co4ERunsMixin:
         if head is not None:
             head.setText(("▾ " if head.isChecked() else "▸ ") + label.upper())
     def _stop_selected_run(self) -> None:
+        """Dừng run đang chọn; không chọn gì thì dừng toàn bộ run của workspace này."""
         row = self.runs_table.currentRow()
         it = self.runs_table.item(row, 0) if row >= 0 else None
         if it is None:
@@ -262,6 +290,7 @@ class Co4ERunsMixin:
         self._run_logs.pop(run_id, None)
         self.manager.remove(run_id)             # emits `changed` → _refresh_runs
     def _runs_context_menu(self, pos) -> None:
+        """Menu chuột phải trên bảng Flow Status: mở, đổi tên, chạy lại, dừng, xoá."""
         from PySide6.QtWidgets import QMenu
         item = self.runs_table.itemAt(pos)
         if item is None:
@@ -321,6 +350,7 @@ class Co4ERunsMixin:
         if self._wf.id == h.wf_id and self.name_edit.text() != new:
             self.name_edit.setText(new)           # updates _wf.name + active tab text
     def _run_selected_in_background(self) -> None:
+        """Chạy luồng đang chọn trong danh sách ở chế độ nền, không mở nó lên khung vẽ."""
         wf = self._selected_wf()
         if wf is None:
             self.status_message.emit(tr("co4e.select_flow"))
diff --git a/presentation/co4e/co4e_sidebar.py b/presentation/co4e/co4e_sidebar.py
index 7418b82..f79d882 100644
--- a/presentation/co4e/co4e_sidebar.py
+++ b/presentation/co4e/co4e_sidebar.py
@@ -20,6 +20,7 @@ from ...presentation.co4e.skills_list_panel import SkillsListPanel
 
 
 class Co4ESidebarMixin:
+    """Cột trái của Co4E Studio: Workflows, Agents, Skills và Flow Status."""
     def _build_sidebar(self) -> QWidget:
         # ONE COLUMN, four named sections — no icon tabs. Every list is on screen
         # at once, so "what can I drag onto the canvas" is answered by looking
@@ -28,6 +29,14 @@ class Co4ESidebarMixin:
         # lists otherwise squeeze down to one visible row each. The splitter
         # hands out the available height by weight and lets the user re-balance
         # it by dragging; each list keeps a small minimum so none disappears.
+        """Dựng cột trái: MỘT cột, bốn mục có tên, không dùng tab icon.
+
+        Mọi danh sách hiện cùng lúc nên câu hỏi "kéo được gì lên khung vẽ" trả lời
+        bằng cách NHÌN, không phải bấm qua ba tab không nhãn. Dùng splitter dọc chứ
+        không xếp cứng: cửa sổ thấp thì bốn danh sách chồng nhau sẽ bị bóp còn đúng
+        một dòng mỗi cái; splitter chia chiều cao theo trọng số và cho người dùng
+        tự cân lại.
+        """
         self._sections: dict = {}
         self.sidebar = QWidget()
         outer_col = QVBoxLayout(self.sidebar)
@@ -42,9 +51,15 @@ class Co4ESidebarMixin:
             """Adapter so the section builders below read the same as before."""
 
             def __init__(self, split):
+                """Bọc một ``QSplitter`` để phần còn lại thao tác với nó như một cột."""
                 self._split = split
 
             def addWidget(self, w, stretch=1):
+                """Thêm một mục vào splitter dọc kèm trọng số chia chiều cao.
+
+                Lớp bọc nhỏ này cho phép dùng splitter ở chỗ mã cũ đang gọi theo API của
+                layout, nên phần dựng mục không phải sửa.
+                """
                 self._split.addWidget(w)
                 self._split.setStretchFactor(self._split.count() - 1, stretch)
 
@@ -203,14 +218,17 @@ class Co4ESidebarMixin:
             box.setMaximumHeight(box.layout().itemAt(0).sizeHint().height() + 4)
         self._sync_section_arrow(key)
     def _sync_section_arrow(self, key: str) -> None:
+        """Cập nhật mũi tên gập/mở và nhãn viết hoa của một mục ở cột trái."""
         head, _body, _s = self._sections[key]
         head.setText(("▾ " if head.isChecked() else "▸ ") + tr(key).upper())
     def _icon_btn(self, icon_name: str, tip_key: str, slot) -> QPushButton:
+        """Dựng một nút icon nhỏ (rộng 34px) kèm tooltip cho hàng công cụ của mục."""
         b = QPushButton(); b.setIcon(icon(icon_name)); b.setToolTip(tr(tip_key))
         b.setFixedWidth(34)
         b.clicked.connect(slot)
         return b
     def _reload_sidebar(self) -> None:
+        """Nạp lại cả bốn danh sách ở cột trái: luồng, agent, skill và Flow Status."""
         self.wf_list.clear()
         for wf in co4e.list_workflows():
             tag = tr("co4e.template") if wf.is_template else tr("co4e.saved")
@@ -246,6 +264,7 @@ class Co4ESidebarMixin:
             self.skill_list.addItem(self._palette_item(name, "sparkle", payload))
     @staticmethod
     def _palette_item(text: str, icon_name: str, payload: dict) -> QListWidgetItem:
+        """Dựng một mục trong bảng nguyên liệu, mang sẵn payload để kéo-thả lên khung vẽ."""
         it = QListWidgetItem(icon(icon_name), text)
         it.setData(Qt.UserRole, payload)
         return it
diff --git a/presentation/co4e/co4e_tab.py b/presentation/co4e/co4e_tab.py
index 5f37a74..6213008 100644
--- a/presentation/co4e/co4e_tab.py
+++ b/presentation/co4e/co4e_tab.py
@@ -36,6 +36,17 @@ mà mọi bước tách widget trước đó đã cố tình né. Trước khi 
 toàn riêng (characterization đầy đủ cho ``Co4ERunManager``) — xem
 ``tests/characterization/test_co4e_run_manager_behavior.py`` hiện có cho một
 phần hành vi, chưa phủ hết 24 điểm gọi này.
+
+SEAM · dựng 2026-08-25 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: ``presentation/shell/bootstrap.py`` gọi ``build_co4e_tab`` thay cho việc dựng thẳng ``ui.co4e_tab.Co4ETab``.
+Để dormant thì sao: Hạn lắp đã ghi trong file là 28/08 và đã qua. Factory
+không ai gọi thì chữ ký của nó không còn được kiểm chứng bởi bất cứ đường
+chạy thật nào.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 
 from __future__ import annotations
diff --git a/presentation/co4e/co4e_workflow_crud.py b/presentation/co4e/co4e_workflow_crud.py
index 71b3181..aabe2de 100644
--- a/presentation/co4e/co4e_workflow_crud.py
+++ b/presentation/co4e/co4e_workflow_crud.py
@@ -16,7 +16,18 @@ from ...presentation.co4e.co4e_chat_view import _skill_names
 
 
 class Co4EWorkflowCrudMixin:
+    """Phần tạo/mở/lưu/xoá luồng của Co4E Studio.
+
+    Tách khỏi ``Co4ETab`` vì đây là nhóm việc trên *danh sách luồng đã lưu*,
+    không phải trên khung vẽ đang mở — dù hai bên nói chuyện với nhau liên tục.
+    """
     def _apply_workflow(self, wf: co4e.Workflow) -> None:
+        """Đưa một luồng lên khung vẽ và chuyển hội thoại sang nhật ký của chính nó.
+
+        KHÔNG xoá ``_flow_outputs``: mỗi luồng giữ ngữ cảnh tích luỹ riêng, đổi
+        tab mà xoá là mất kết quả của luồng khác. Luồng cũ xếp dọc thì tự bẻ lại
+        thành trái→phải cho khớp bố cục hiện tại.
+        """
         self._wf = wf
         # Per-flow outputs are kept in self._flow_outputs[wf.id] — do NOT clear
         # here (switching tabs must not wipe another flow's accumulated context).
@@ -31,6 +42,13 @@ class Co4EWorkflowCrudMixin:
         self._update_run_btn()                   # reflect THIS flow's run state
         self._refresh_usage_total()              # show THIS flow's token/cost total
     def _new_workflow(self) -> None:
+        """Tạo luồng trống mới, đưa con trỏ vào ô tên và báo trạng thái.
+
+        Trước đây bấm nút này khi khung vẽ đã có sẵn một luồng trống chưa đặt tên
+        sẽ tạo ra một luồng trống y hệt — đúng logic nhưng nhìn không thấy gì đổi,
+        nên nút bị hiểu là hỏng. Giờ nói rõ vừa xảy ra chuyện gì và đặt con trỏ
+        vào đúng việc tiếp theo: đặt tên.
+        """
         self._open_flow(co4e.new_workflow(tr("co4e.untitled")))
         # Pressing this while the canvas already holds an empty untitled flow
         # produced an identical empty untitled flow — correct, and completely
@@ -47,16 +65,19 @@ class Co4EWorkflowCrudMixin:
         _kind, ident = item.data(Qt.UserRole)
         return co4e.get_workflow(ident)
     def _load_selected_workflow(self, *_a) -> None:
+        """Mở luồng đang chọn trong danh sách (hoặc chuyển sang tab của nó nếu đã mở)."""
         wf = self._selected_wf()
         if wf is not None:
             self._open_flow(wf)          # open (or focus) its browser-style tab
     def _edit_selected_workflow(self) -> None:
+        """Mở luồng đang chọn để sửa; chưa chọn gì thì nhắc người dùng chọn."""
         wf = self._selected_wf()
         if wf is None:
             self.status_message.emit(tr("co4e.select_flow"))
             return
         self._open_flow(wf)
     def _duplicate_selected_workflow(self) -> None:
+        """Nhân bản luồng đang chọn thành một luồng mới rồi nạp lại danh sách."""
         wf = self._selected_wf()
         if wf is None:
             self.status_message.emit(tr("co4e.select_flow"))
@@ -65,6 +86,7 @@ class Co4EWorkflowCrudMixin:
         self._reload_sidebar()
         self.status_message.emit(tr("co4e.duplicated_msg", name=dup.name))
     def _wf_context_menu(self, pos) -> None:
+        """Menu chuột phải trên danh sách luồng: sửa, đổi tên, nhân bản, chạy nền, xoá."""
         lw = self.wf_list
         item = lw.itemAt(pos)
         if item is None:
@@ -106,6 +128,7 @@ class Co4EWorkflowCrudMixin:
         self._reload_sidebar()
         self.status_message.emit(tr("co4e.renamed_msg", name=name))
     def _delete_selected_workflow(self) -> None:
+        """Xoá luồng đang chọn khỏi đĩa rồi nạp lại danh sách."""
         item = self.wf_list.currentItem()
         if item is None:
             return
@@ -113,26 +136,34 @@ class Co4EWorkflowCrudMixin:
         co4e.delete_workflow(ident)
         self._reload_sidebar()
     def _sync_wf_from_canvas(self) -> None:
+        """Chép node, cạnh và tên từ khung vẽ về đối tượng luồng trước khi lưu."""
         self._wf.nodes = self.canvas.nodes()
         self._wf.edges = self.canvas.edges()
         self._wf.name = self.name_edit.text().strip() or tr("co4e.untitled")
     def _save(self, as_template: bool) -> None:
+        """Lưu luồng đang mở; ``as_template`` đánh dấu nó là mẫu dùng lại được."""
         self._sync_wf_from_canvas()
         self._wf.is_template = as_template
         co4e.save_workflow(self._wf)
         self._reload_sidebar()
         self.status_message.emit(tr("co4e.saved_msg", name=self._wf.name))
     def _autosave(self) -> None:
+        """Tự lưu sau mỗi thay đổi trên khung vẽ — nhưng chỉ với luồng ĐÃ tồn tại
+        trên đĩa, để luồng nháp chưa đặt tên không tự nhảy vào danh sách.
+        """
         if co4e.get_workflow(self._wf.id) is not None:
             self._sync_wf_from_canvas()
             co4e.save_workflow(self._wf)
     def _on_name_changed(self, text: str) -> None:
+        """Gõ tên mới thì cập nhật luôn nhãn tab của luồng đang mở."""
         self._wf.name = text.strip() or tr("co4e.untitled")
         self._sync_active_flow_tab_text()
     def _add_blank_step(self) -> None:
+        """Thêm một bước trống vào giữa khung nhìn hiện tại."""
         self.canvas.add_palette_step(co4e.Step(label="New Step"),
                                      self.canvas.mapToScene(self.canvas.rect().center()))
     def _on_node_selected(self, node_id: str) -> None:
+        """Chọn một node thì nạp bước đó vào bảng thuộc tính, tự mở bảng nếu đang gập."""
         for n in self.canvas.nodes():
             if n.id == node_id:
                 self.config.load_step(node_id, n.data, _skill_names())
@@ -140,6 +171,7 @@ class Co4EWorkflowCrudMixin:
                     self._toggle_config()
                 return
     def _on_config_changed(self) -> None:
+        """Sửa thuộc tính bước thì vẽ lại mọi node (nhãn/model có thể đổi) rồi tự lưu."""
         for n in self.canvas.nodes():
             self.canvas.refresh_node(n.id)
         self._autosave()
diff --git a/presentation/co4e/node_property_actions_mixin.py b/presentation/co4e/node_property_actions_mixin.py
index 81c5ed8..20e16a6 100644
--- a/presentation/co4e/node_property_actions_mixin.py
+++ b/presentation/co4e/node_property_actions_mixin.py
@@ -64,6 +64,7 @@ class _StepConfigActionsMixin:
         return names
 
     def _add_subagent(self) -> None:
+        """Thêm một sub-agent vào bước đang chọn (chạy song song trong bước đó)."""
         if self._step is None:
             return
         from PySide6.QtWidgets import QInputDialog
@@ -102,6 +103,7 @@ class _StepConfigActionsMixin:
             self.changed.emit()
 
     def _del_subagent(self) -> None:
+        """Xoá sub-agent đang chọn khỏi bước."""
         if self._step is None:
             return
         row = self.sub_list.currentRow()
@@ -111,6 +113,7 @@ class _StepConfigActionsMixin:
             self.changed.emit()
 
     def _add_attachment(self) -> None:
+        """Đính kèm tệp vào bước đang chọn."""
         if self._step is None:
             return
         from pathlib import Path as _P
@@ -127,6 +130,7 @@ class _StepConfigActionsMixin:
             self.changed.emit()
 
     def _del_attachment(self) -> None:
+        """Gỡ tệp đính kèm đang chọn khỏi bước."""
         if self._step is None:
             return
         row = self.attach_list.currentRow()
@@ -156,11 +160,13 @@ class _StepConfigActionsMixin:
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: nhờ model soạn thử prompt cho agent theo tên, vai trò và gợi ý."""
             from ...core.ai_task_planner import generate_agent_prompt
             return {"text": generate_agent_prompt(ctx.build_active_provider(), name, role, hint,
                                                   cancel=worker.is_cancelled)}
 
         def done(result: dict):
+            """Đổ prompt vừa soạn vào ô chỉ dẫn (``_on_edit`` sẽ tự lưu lại)."""
             self.gen_btn.setEnabled(True)
             if result.get("text"):
                 self.instructions_edit.setPlainText(result["text"])   # _on_edit persists it
@@ -172,6 +178,7 @@ class _StepConfigActionsMixin:
         w.start()
 
     def _load_models(self) -> None:
+        """Nạp danh sách model đang chạy được vào ô chọn của bước, ở luồng nền."""
         if self.ctx is None:
             return
         from ...core import preview_ai
@@ -181,9 +188,11 @@ class _StepConfigActionsMixin:
         ctx = self.ctx
 
         def job(_w):
+            """Chạy nền: hỏi mọi provider danh sách model đang sống."""
             return preview_ai.fetch_live_models(ctx)
 
         def done(result: dict):
+            """Gộp model của mọi provider vào ô chọn, giữ nguyên thứ đang chọn."""
             self.load_models_btn.setEnabled(True)
             models = []
             for lst in (result or {}).values():
diff --git a/presentation/co4e/node_property_panel.py b/presentation/co4e/node_property_panel.py
index 79e8b7e..7e256a4 100644
--- a/presentation/co4e/node_property_panel.py
+++ b/presentation/co4e/node_property_panel.py
@@ -46,12 +46,20 @@ from .step_config_section import _add_section
 
 
 class StepConfigPanel(_StepConfigActionsMixin, QScrollArea):
+    """Bảng thuộc tính bên phải khung vẽ Co4E: sửa nhãn, vai trò, model, chỉ dẫn,
+    skill, sub-agent và tệp đính kèm của một bước.
+    """
     changed = Signal()            # any field edited → repaint node + autosave
     run_node = Signal(str)        # "Run this step" (node id)
     run_from = Signal(str)        # "Run from here"
     delete_node = Signal(str)     # "Delete step"
 
     def __init__(self, ctx=None):
+        """Panel cấu hình cho bước đang chọn.
+
+        ``_loading`` chặn tín hiệu trong lúc đổ dữ liệu vào form: không có nó thì
+        chính việc đổ dữ liệu sẽ bị hiểu là người dùng vừa sửa.
+        """
         super().__init__()
         self.ctx = ctx
         self._step: Optional[Step] = None
@@ -229,6 +237,11 @@ class StepConfigPanel(_StepConfigActionsMixin, QScrollArea):
 
     # ---- load a step ------------------------------------------------------
     def load_step(self, node_id: str, step: Step, skill_names: List[str]) -> None:
+        """Nạp một bước lên bảng.
+
+        Bật cờ ``_loading`` trong lúc điền để việc đặt giá trị không bị hiểu nhầm là
+        người dùng vừa sửa và kích hoạt tự lưu.
+        """
         self._loading = True
         self._node_id = node_id
         self._step = step
@@ -269,12 +282,14 @@ class StepConfigPanel(_StepConfigActionsMixin, QScrollArea):
         self._loading = False
 
     def clear_step(self) -> None:
+        """Xoá bảng khi không có bước nào được chọn."""
         self._step = None
         self._node_id = ""
         self.setEnabled(False)
 
     # ---- edits write back to the Step -------------------------------------
     def _on_edit(self, *_a) -> None:
+        """Người dùng sửa một trường: ghi vào bước rồi báo ra ngoài để vẽ lại node và tự lưu."""
         if self._loading or self._step is None:
             return
         s = self._step
diff --git a/presentation/co4e/palette_list.py b/presentation/co4e/palette_list.py
index 8844b0c..53e95e7 100644
--- a/presentation/co4e/palette_list.py
+++ b/presentation/co4e/palette_list.py
@@ -36,12 +36,16 @@ class _PaletteList(QListWidget):
     Workflow rows also keep a (kind, id) tuple in Qt.UserRole for load/delete."""
 
     def __init__(self, parent=None, payload_role=Qt.UserRole):
+        """Danh sách nguyên liệu chỉ để kéo ra khung vẽ — không nhận thả vào."""
         super().__init__(parent)
         self._payload_role = payload_role
         self.setDragEnabled(True)
         self.setDragDropMode(QListWidget.DragOnly)
 
     def startDrag(self, _actions):  # noqa: N802
+        """Bắt đầu kéo: gói dữ liệu của mục đang chọn vào MIME riêng của Co4E, để khung
+        vẽ nhận ra và dựng đúng loại node.
+        """
         item = self.currentItem()
         if item is None:
             return
diff --git a/presentation/co4e/skills_list_panel.py b/presentation/co4e/skills_list_panel.py
index 7c6befe..a469b4a 100644
--- a/presentation/co4e/skills_list_panel.py
+++ b/presentation/co4e/skills_list_panel.py
@@ -44,6 +44,11 @@ class SkillsListPanel(QWidget):
     """
 
     def __init__(self, parent: QWidget | None = None) -> None:
+        """Danh sách skill ở cột trái Co4E Studio, kèm nút quản lý.
+
+        Không nối ``clicked`` ở đây: bên gọi (``Co4ETab``) tự quyết định nút ấy mở
+        cái gì.
+        """
         super().__init__(parent)
         self.manage_btn = QPushButton(tr("co4e.manage_skills"))
         self.manage_btn.setToolTip(tr("co4e.tt_manage_skills"))
diff --git a/presentation/co4e/step_config_section.py b/presentation/co4e/step_config_section.py
index a7345fa..4e1752b 100644
--- a/presentation/co4e/step_config_section.py
+++ b/presentation/co4e/step_config_section.py
@@ -40,6 +40,7 @@ class _SectionHeader(QLabel):
     clicked = Signal()
 
     def mousePressEvent(self, event) -> None:  # noqa: N802
+        """Bấm trái vào tiêu đề mục thì gập/mở mục đó."""
         if event.button() == Qt.LeftButton:
             self.clicked.emit()
         super().mousePressEvent(event)
@@ -52,6 +53,13 @@ class _SectionHeader(QLabel):
         # _add_section is briefly wrong (too tall) until something else
         # triggers a relayout. Recomputing here, every time the label
         # actually becomes visible, means the first paint is never stale.
+        """Tính lại chiều cao cố định mỗi lần nhãn thật sự hiện ra.
+
+        ``fontMetrics()`` lúc dựng chỉ phản ánh cỡ chữ trong QSS nếu style đã được
+        áp xong — ở lần vẽ ĐẦU TIÊN của màn Co4E thì đôi khi chưa, nên chiều cao
+        tính trong ``_add_section`` bị sai (quá cao) cho tới khi có gì đó buộc bố
+        cục tính lại. Tính lại ở đây thì lần vẽ đầu không bao giờ còn lệch.
+        """
         self.setFixedHeight(self.fontMetrics().height())
         super().showEvent(event)
 
@@ -105,6 +113,9 @@ def _add_section(outer: QVBoxLayout, title: str) -> tuple[QFormLayout, QWidget]:
     is_open = False
 
     def _on_finished() -> None:
+        """Hiệu ứng gập/mở chạy xong: bỏ trần chiều cao khi đang mở, để bước có nhiều
+        trường không bị cắt cụt.
+        """
         if is_open:
             # Uncapped once open, so switching to a step whose fields make
             # this section taller/shorter (e.g. a parallel node's sub-agent
@@ -116,6 +127,7 @@ def _add_section(outer: QVBoxLayout, title: str) -> tuple[QFormLayout, QWidget]:
     anim.finished.connect(_on_finished)
 
     def _toggle() -> None:
+        """Lật trạng thái gập/mở của một mục và chạy hiệu ứng tương ứng."""
         nonlocal is_open
         is_open = not is_open
         header.setText(f"{'▼' if is_open else '▶'} {title}")
diff --git a/presentation/dashboard/dashboard_tab.py b/presentation/dashboard/dashboard_tab.py
index 30e868e..2f34b8e 100644
--- a/presentation/dashboard/dashboard_tab.py
+++ b/presentation/dashboard/dashboard_tab.py
@@ -25,9 +25,17 @@ from cowork_local.ui.icons import icon
 
 
 class DashboardTab(QWidget):
+    """Màn Bảng điều khiển: ghép thẻ số liệu, biểu đồ và bảng thói quen dùng model.
+
+    Một ``DashboardQueryService`` duy nhất được dựng ở đây và dùng chung cho cả
+    ba thẻ con, nên đơn giá và tiền tệ luôn nhất quán trên toàn màn hình.
+    """
     status_message = Signal(str)
 
     def __init__(self, ctx: AppContext):
+        """Dựng vỏ Bảng điều khiển và ghép ba thẻ con, dùng chung một
+        ``DashboardQueryService``.
+        """
         super().__init__()
         self.ctx = ctx
         self._query = DashboardQueryService(ctx)
@@ -52,12 +60,19 @@ class DashboardTab(QWidget):
         head.addWidget(self.refresh_btn)
         root.addLayout(head)
 
-        self.token_cards = TokenUsageCardWidget(ctx, self._query)
-        root.addWidget(self.token_cards)
-
         self.chart = UsageChartWidget(ctx, self._query)
         self.chart.period_changed.connect(self.refresh)
         self.chart.currency_changed.connect(self.refresh)
+
+        # Hàng bộ chọn kỳ đặt NGAY DƯỚI TIÊU ĐỀ, trên các thẻ số liệu — đúng
+        # chỗ của nó trước refactor. Nó lọc cả ba thẻ con chứ không riêng biểu đồ,
+        # nên để nó nằm dưới các thẻ số liệu là bắt người dùng đọc con số trước
+        # khi thấy con số đó tính cho kỳ nào (F-07).
+        root.addWidget(self.chart.detach_controls_bar())
+
+        self.token_cards = TokenUsageCardWidget(ctx, self._query)
+        root.addWidget(self.token_cards)
+
         root.addWidget(self.chart)
 
         self.habits = HabitsWidget(ctx, self._query)
@@ -74,6 +89,7 @@ class DashboardTab(QWidget):
         self.refresh()
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn, rồi vẽ lại số liệu."""
         self._title.setText(tr("dashboard.title"))
         self.refresh_btn.setToolTip(tr("dashboard.refresh_tooltip"))
         self.token_cards.retranslate()
@@ -82,6 +98,7 @@ class DashboardTab(QWidget):
         self.refresh()
 
     def refresh(self, *_a) -> None:
+        """Đọc lại số liệu cho kỳ đang chọn và cập nhật cả ba thẻ con."""
         start, end = self.chart.period_range()
         self.token_cards.refresh(start, end)
         self.chart.refresh()
diff --git a/presentation/dashboard/habits_widget.py b/presentation/dashboard/habits_widget.py
index 34b90ce..c9dcd70 100644
--- a/presentation/dashboard/habits_widget.py
+++ b/presentation/dashboard/habits_widget.py
@@ -20,9 +20,19 @@ from cowork_local.ui.widgets import fmt_tokens
 
 
 class HabitsWidget(QWidget):
+    """Thẻ "Thói quen dùng model" của Dashboard, kèm phần AI phân tích.
+
+    Chỉ gửi SỐ LIỆU đã tổng hợp lên provider, không bao giờ gửi nội dung
+    prompt thật — xem :meth:`_ai_analyze`.
+    """
     status_message = Signal(str)
 
     def __init__(self, ctx, query: DashboardQueryService, parent=None):
+        """Bảng thói quen dùng model, kèm nút nhờ model tự nhận xét.
+
+        Kỳ đang xem được nhớ lại ở mỗi lần ``refresh()`` để nút nhận xét dùng đúng
+        khoảng thời gian đang hiện trên màn hình.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._query = query
@@ -64,6 +74,7 @@ class HabitsWidget(QWidget):
         self.retranslate()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.ai_analyze_btn.setText(tr("dashboard.ai_analyze_btn"))
         self.ai_analyze_btn.setToolTip(tr("dashboard.ai_analyze_tooltip"))
         self.apply_strategy_btn.setText(tr("dashboard.strategy_btn"))
@@ -71,6 +82,7 @@ class HabitsWidget(QWidget):
         self._habits_title.setText(tr("dashboard.habits_title"))
 
     def refresh(self, start: date, end: date) -> None:
+        """Vẽ lại bảng thói quen dùng model cho một kỳ, và nhớ kỳ đó cho nút AI phân tích."""
         self._period_range = (start, end)
         summary = self._query.summary(start, end)
         s, events = summary["stats"], summary["events"]
@@ -134,6 +146,9 @@ class HabitsWidget(QWidget):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: gửi SỐ LIỆU đã tổng hợp (không bao giờ gửi nội dung prompt thật)
+            cho model và xin nhận xét cùng gợi ý tiết kiệm token.
+            """
             from cowork_local.core import usage_tracker as ut
             from cowork_local.i18n import get_language
 
@@ -144,6 +159,7 @@ class HabitsWidget(QWidget):
             return {"text": (reply.get("content") or "").strip()}
 
         def done(result: dict) -> None:
+            """Hiện nhận xét của AI và mở nút "Áp dụng chiến lược tiết kiệm"."""
             self._ai_worker = None
             self.ai_analyze_btn.setEnabled(True)
             self.ai_analyze_btn.setText(tr("dashboard.ai_analyze_btn"))
@@ -156,6 +172,7 @@ class HabitsWidget(QWidget):
                 self.apply_strategy_btn.setVisible(True)
 
         def failed(err: str) -> None:
+            """Phân tích lỗi: hiện lý do và mở khoá lại nút."""
             self._ai_worker = None
             self.ai_analyze_btn.setEnabled(True)
             self.ai_analyze_btn.setText(tr("dashboard.ai_analyze_btn"))
diff --git a/presentation/dashboard/token_usage_card_widget.py b/presentation/dashboard/token_usage_card_widget.py
index 12527d9..9dd1195 100644
--- a/presentation/dashboard/token_usage_card_widget.py
+++ b/presentation/dashboard/token_usage_card_widget.py
@@ -22,11 +22,16 @@ class TokenUsageCardWidget(QWidget):
     tiles — with six equal cards nothing said which number mattered."""
 
     def __init__(self, ctx, query: DashboardQueryService, parent=None):
+        """Lưới các thẻ số liệu token và chi phí."""
         super().__init__(parent)
         self.ctx = ctx
         self._query = query
 
         cards_grid = QGridLayout(self)
+        # Lề 0 như hai thẻ con còn lại (``habits_widget``, ``usage_chart_widget``):
+        # bản trước refactor đổ lưới thẻ THẲNG vào layout của màn hình, nên bọc nó
+        # vào một widget kèm lề mặc định 9px đẩy cả hàng thẻ xuống 9px so với bản vẽ.
+        cards_grid.setContentsMargins(0, 0, 0, 0)
         cards_grid.setSpacing(8)
         self.card_total = StatCard()
         self.card_in = StatCard()
@@ -50,10 +55,12 @@ class TokenUsageCardWidget(QWidget):
         self.retranslate()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.budget_card.apply_btn.setToolTip(tr("usage.budget_apply_tooltip"))
         self.budget_card.budget_spin.setToolTip(tr("usage.budget_spin_tooltip"))
 
     def refresh(self, start: date, end: date) -> None:
+        """Cập nhật mọi thẻ theo số liệu của một kỳ."""
         summary = self._query.summary(start, end)
         s, pricing, costs = summary["stats"], summary["pricing"], summary["costs"]
         from cowork_local.core import usage_tracker as ut
@@ -81,6 +88,7 @@ class TokenUsageCardWidget(QWidget):
         self._refresh_budget()
 
     def _refresh_budget(self) -> None:
+        """Cập nhật thẻ ngân sách: còn lại / tổng, phần trăm đã dùng, cảnh báo khi vượt."""
         from cowork_local.core import model_pricing as mp
         from cowork_local.core import usage_tracker as ut
 
diff --git a/presentation/dashboard/usage_chart_widget.py b/presentation/dashboard/usage_chart_widget.py
index 81571d6..efa7397 100644
--- a/presentation/dashboard/usage_chart_widget.py
+++ b/presentation/dashboard/usage_chart_widget.py
@@ -24,18 +24,30 @@ from cowork_local.ui.widgets import fmt_tokens
 
 
 class UsageChartWidget(QWidget):
+    """Thẻ biểu đồ chi phí/token của Dashboard: hàng điều khiển + đồ thị spline.
+
+    Đây cũng là nơi giữ *kỳ đang xem* (độ mịn tuần/tháng/năm + độ lệch kỳ)
+    cho cả màn hình: các thẻ khác không tự chọn kỳ mà nghe tín hiệu
+    ``period_changed`` rồi hỏi lại :meth:`period_range`.
+    """
     period_changed = Signal()     # granularity or offset changed — re-run every widget
     currency_changed = Signal()   # display currency changed — same, cost text depends on it
 
     def __init__(self, ctx, query: DashboardQueryService, parent=None):
+        """Dựng hàng điều khiển kỳ và biểu đồ spline."""
         super().__init__(parent)
         self.ctx = ctx
         self._query = query
         self._chart_offset = 0    # 0 = current period; <0 = a past period
 
-        root = QVBoxLayout(self)
-        root.setContentsMargins(0, 0, 0, 0)
-        controls = QHBoxLayout()
+        self._root = QVBoxLayout(self)
+        self._root.setContentsMargins(0, 0, 0, 0)
+        # Hàng điều khiển nằm trong một widget riêng chứ không đổ thẳng vào layout,
+        # để vỏ ngoài gỡ được nó ra và đặt lên đầu màn hình — xem
+        # :meth:`detach_controls_bar`.
+        self.controls_bar = QWidget(self)
+        controls = QHBoxLayout(self.controls_bar)
+        controls.setContentsMargins(0, 0, 0, 0)
         controls.setSpacing(6)
         self.chart_prev_btn = QPushButton()
         self.chart_prev_btn.setIcon(icon("chevron-left"))
@@ -79,19 +91,36 @@ class UsageChartWidget(QWidget):
         self.currency_combo.setCurrentIndex(max(0, idx))
         self.currency_combo.currentIndexChanged.connect(self._on_currency_changed)
         controls.addWidget(self.currency_combo)
-        root.addLayout(controls)
+        self._root.addWidget(self.controls_bar)
 
         chart_head = QHBoxLayout()
         self._chart_title = QLabel()
         self._chart_title.setStyleSheet("font-weight:600;")
         chart_head.addWidget(self._chart_title, 1)
-        root.addLayout(chart_head)
+        self._root.addLayout(chart_head)
         self.chart = SplineChart()
-        root.addWidget(self.chart)
+        self._root.addWidget(self.chart)
 
         self.retranslate()
 
+    def detach_controls_bar(self) -> QWidget:
+        """Gỡ hàng điều khiển ra khỏi thẻ biểu đồ và trả về cho chỗ khác đặt.
+
+        Hàng này chọn kỳ cho **cả màn hình** chứ không riêng biểu đồ: thẻ số
+        liệu và bảng thói quen đều lọc theo nó. Bản trước refactor vì thế đặt nó
+        ngay dưới tiêu đề, trên các thẻ số liệu; đợt tách widget (R08-T13) kéo
+        nó xuống theo biểu đồ, thành ra người dùng đọc các thẻ số liệu trước khi
+        nhìn thấy thứ quyết định những con số ấy (F-07).
+
+        Trạng thái kỳ và toàn bộ dây tín hiệu vẫn thuộc widget này — chỉ có chỗ
+        đặt là đổi. Gọi hay không gọi đều chạy đúng: không gọi thì hàng điều khiển
+        ở nguyên trong thẻ biểu đồ (widget dùng độc lập trong test vẫn đủ bộ).
+        """
+        self._root.removeWidget(self.controls_bar)
+        return self.controls_bar
+
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho nhãn và tooltip."""
         self.currency_lbl.setText(tr("monitoring.overview_currency"))
         self.currency_combo.setToolTip(tr("dashboard.currency_tooltip"))
         self._chart_title.setText(tr("dashboard.chart_title"))
@@ -100,29 +129,42 @@ class UsageChartWidget(QWidget):
 
     # ---- public: the period selector every other widget follows ------------- #
     def granularity(self) -> str:
+        """Độ mịn đang chọn: 'week' | 'month' | 'year'. Mặc định 'week'."""
         return self.gran_combo.currentData() or "week"
 
     @property
     def chart_offset(self) -> int:
+        """Độ lệch kỳ: 0 là kỳ hiện tại, số âm là lùi về quá khứ."""
         return self._chart_offset
 
     def period_range(self) -> Tuple:
+        """Khoảng thời gian (đầu, cuối) của kỳ đang xem — thứ mọi thẻ khác dùng để lọc dữ liệu."""
         return self._query.period_range(self.granularity(), self._chart_offset)
 
     # ---- navigation ------------------------------------------------------------ #
     def _on_gran_changed(self, *_a) -> None:
+        """Đổi độ mịn thì nhảy về kỳ hiện tại: giữ nguyên độ lệch cũ sẽ nhảy sang
+        một mốc thời gian khác hẳn (lùi 3 tuần ≠ lùi 3 tháng).
+        """
         self._chart_offset = 0            # period size changed → back to current
         self.period_changed.emit()
 
     def _chart_prev(self) -> None:
+        """Lùi một kỳ."""
         self._chart_offset -= 1
         self.period_changed.emit()
 
     def _chart_next(self) -> None:
+        """Tiến một kỳ, chặn ở kỳ hiện tại — không cho xem tương lai."""
         self._chart_offset = min(0, self._chart_offset + 1)   # never past the present
         self.period_changed.emit()
 
     def _on_currency_changed(self, _idx: int) -> None:
+        """Đổi tiền tệ hiển thị và ghi vào cấu hình ngay.
+
+        Dashboard và Giám sát dùng chung khoá ``usage.currency`` nên đổi ở đây
+        là mọi chỗ hiện tiền đều đổi theo.
+        """
         cur = self.currency_combo.currentData()
         if not cur:
             return
diff --git a/presentation/folder/ai_edit_model_resolver.py b/presentation/folder/ai_edit_model_resolver.py
index 8e7d270..7222751 100644
--- a/presentation/folder/ai_edit_model_resolver.py
+++ b/presentation/folder/ai_edit_model_resolver.py
@@ -36,6 +36,11 @@ class AiEditModelResolver:
     """
 
     def __init__(self, ctx, model_combo, on_status, confirm_switch) -> None:
+        """Bộ chọn model của panel AI-Edit.
+
+        ``on_status`` và ``confirm_switch`` được tiêm vào để lớp này không tự mở hộp
+        thoại — nhờ vậy test chạy được nó mà không cần giao diện.
+        """
         self.ctx = ctx
         self._combo = model_combo
         self._on_status = on_status
@@ -50,10 +55,12 @@ class AiEditModelResolver:
 
     @property
     def models(self) -> List[str]:
+        """Danh sách model đã nạp cho provider hiện tại."""
         return self._models
 
     @property
     def models_provider(self) -> str:
+        """Provider mà danh sách model đang thuộc về; '' nếu chưa nạp lần nào."""
         return self._models_provider
 
     @property
@@ -64,6 +71,7 @@ class AiEditModelResolver:
 
     @property
     def routed_model(self) -> Optional[str]:
+        """Model do định tuyến tự động chọn cho lượt này; ``None`` nếu dùng model người dùng chọn."""
         return self._routed_model
 
     def should_refresh(self) -> bool:
@@ -80,6 +88,7 @@ class AiEditModelResolver:
         setting_model = self.ctx.config.provider_conf(name).get("model", "")
 
         def job(worker):
+            """Chạy nền: hỏi provider danh sách model, lỗi thì trả về list rỗng."""
             prov = self.ctx.build_provider_for(name)
             try:
                 models = list(getattr(prov, "list_models", lambda: [])() or [])
@@ -88,6 +97,11 @@ class AiEditModelResolver:
             return {"models": models}
 
         def done(res):
+            """Đổ danh sách vào ô chọn, giữ nguyên model đang chọn.
+
+            Luôn đưa model cấu hình trong Settings lên đầu, kể cả khi provider không
+            liệt kê được — để ô chọn không bao giờ chỉ có mỗi "(tự động)".
+            """
             fetched = list(res.get("models", []))
             # Always offer the Settings-configured model as an explicit
             # choice, even when the provider can't list models.
@@ -111,6 +125,11 @@ class AiEditModelResolver:
         self._scan_all_image_models()
 
     def _scan_all_image_models(self, then_suggest: bool = False) -> None:
+        """Dò khắp mọi provider đã cấu hình xem cái nào có model sinh ảnh.
+
+        Chạy sẵn ở nền để lúc cần gợi ý là có ngay. Đang dò dở mà bị gọi lại thì
+        chỉ ghi nhận yêu cầu gợi ý, không dò chồng lên nhau.
+        """
         if self._img_scan_worker is not None:
             if then_suggest:
                 self._pending_img_suggest = True
@@ -120,6 +139,7 @@ class AiEditModelResolver:
                       if (c.get("base_url") or c.get("api_key"))]
 
         def job(worker):
+            """Chạy nền: duyệt từng provider, lọc ra model sinh ảnh được."""
             from cowork_local.core import image_gen
             found = []
             for key in candidates:
@@ -134,6 +154,7 @@ class AiEditModelResolver:
             return {"found": found}
 
         def done(res):
+            """Ghi lại kết quả dò; có yêu cầu gợi ý đang chờ thì trả lời luôn."""
             self._img_scan_worker = None
             self._all_image_models = list(res.get("found", []))
             if self._pending_img_suggest:
@@ -149,6 +170,9 @@ class AiEditModelResolver:
         w.start()
 
     def _on_image_scan_failed(self, _err) -> None:
+        """Dò model ảnh thất bại: chỉ xoá cờ đang chạy, không báo lỗi ra màn hình —
+        đây là việc chạy ngầm mà người dùng không yêu cầu.
+        """
         self._img_scan_worker = None
 
     def provider(self) -> Any:
@@ -208,6 +232,10 @@ class AiEditModelResolver:
             self._scan_all_image_models(then_suggest=True)
 
     def _suggest_cross_provider_image(self) -> None:
+        """Gợi ý một model sinh ảnh, kể cả khi nó thuộc provider KHÁC provider đang chọn.
+
+        Đây là chỗ duy nhất trong màn Thư mục biết tới nhiều provider cùng lúc.
+        """
         from cowork_local.config import PROVIDER_LABELS
         if not self._all_image_models:
             picked = self._combo.currentData()
diff --git a/presentation/folder/ai_edit_pipeline.py b/presentation/folder/ai_edit_pipeline.py
index f8b9b28..d2ef31e 100644
--- a/presentation/folder/ai_edit_pipeline.py
+++ b/presentation/folder/ai_edit_pipeline.py
@@ -36,6 +36,11 @@ class AiEditPipeline:
     """
 
     def __init__(self, owner) -> None:
+        """Vòng chạy một lượt sửa tệp bằng AI.
+
+        ``pending`` giữ nội dung model đề xuất cho tới khi người dùng đồng ý: không
+        bao giờ ghi đè tệp trước khi có xác nhận.
+        """
         self._owner = owner
         self.worker: Optional[AgentWorker] = None
         self.pending: Optional[dict] = None   # proposed content awaiting confirmation
@@ -72,6 +77,7 @@ class AiEditPipeline:
 
     # ---- usage accounting (like Cowork's per-message footer) --------------- #
     def _add_usage(self, usage) -> None:
+        """Cộng dồn token của một lượt gọi vào tổng của cả phiên sửa file."""
         if not isinstance(usage, dict):
             return
         tot = self._prompt_usage
@@ -81,6 +87,7 @@ class AiEditPipeline:
         tot["cost"] += float(usage.get("cost_usd", 0.0) or 0.0)
 
     def _show_usage(self, bubble) -> None:
+        """Gắn dòng token/chi phí dưới bong bóng trả lời; chưa dùng token nào thì bỏ qua."""
         tot = self._prompt_usage
         if bubble is None or not (tot["in"] or tot["out"]):
             return
@@ -96,12 +103,14 @@ class AiEditPipeline:
 
     # ---- phase 1: plan ------------------------------------------------------- #
     def _run_plan(self) -> None:
+        """Bước 1 — nhờ model lập kế hoạch sửa trước khi động vào nội dung."""
         o = self._owner
         c = self._ctx
         plan_bubble = o.ai_chat.add_plan(tr("folder.ai_planning"))
         o.ai_chat.scroll_to_bottom()
 
         def job(worker):
+            """Chạy nền: gọi model sinh kế hoạch và đo token đã dùng."""
             from cowork_local.core import usage_tracker as ut
             from cowork_local.core.co4e_runner import _usage_delta
             provider = c["provider"]
@@ -131,6 +140,7 @@ class AiEditPipeline:
         worker.start()
 
     def _plan_done(self, result, plan_bubble) -> None:
+        """Có kế hoạch: hiện ra rồi chuyển sang bước sửa thật."""
         self._add_usage((result or {}).get("usage"))
         plan = ((result or {}).get("plan") or "").strip()
         self._ctx["plan"] = plan
@@ -140,6 +150,7 @@ class AiEditPipeline:
 
     # ---- phase 2: execute (edit the file) ------------------------------------ #
     def _run_edit(self) -> None:
+        """Bước 2 — sinh nội dung mới, phát dần vào bong bóng trả lời."""
         o = self._owner
         c = self._ctx
         bubble = o.ai_chat.add_assistant(tr("folder.ai_edit"))
@@ -178,6 +189,7 @@ class AiEditPipeline:
             pass
 
         def job(worker):
+            """Chạy nền: gọi model sinh nội dung sửa, kèm ngữ cảnh tệp đang mở."""
             provider = c["provider"]
             open_note = (f"the currently-open file '{c['filename']}'" if c["filename"]
                          else "no file is open")
@@ -199,6 +211,7 @@ class AiEditPipeline:
             messages.append({"role": "user", "content": cur + f"Request: {c['instruction']}"})
 
             def on_text(piece: str) -> None:
+                """Đẩy từng mẩu nội dung ra ngoài để giao diện vẽ dần."""
                 worker.emit_event({"type": "text", "delta": piece})
 
             from cowork_local.core import usage_tracker as ut
@@ -221,11 +234,17 @@ class AiEditPipeline:
         worker.start()
 
     def _stream(self, ev, bubble) -> None:
+        """Vẽ từng mẩu nội dung đang phát dần và cuộn theo."""
         if isinstance(ev, dict) and ev.get("type") == "text":
             bubble.append_delta(ev.get("delta", ""))
             self._owner.ai_chat.scroll_to_bottom()
 
     def _done(self, result, bubble) -> None:
+        """Sinh xong: tách phần mã khỏi phần giải thích và dựng bản xem trước.
+
+        KHÔNG bao giờ ghi thẳng ra tệp ở đây — chỉ ``_finalize_apply`` mới chạm đĩa,
+        và chỉ sau khi người dùng bấm Áp dụng.
+        """
         o = self._owner
         self.worker = None
         o.set_busy(False)
@@ -281,6 +300,10 @@ class AiEditPipeline:
         self._finalize_apply(p)
 
     def _generate_then_finalize(self, p: dict) -> None:
+        """Lượt sửa có yêu cầu sinh ảnh: tạo ảnh trước rồi mới ghi nội dung.
+
+        Phải theo thứ tự đó vì nội dung có thể tham chiếu tới đường dẫn ảnh vừa tạo.
+        """
         o = self._owner
         imgs = p.get("image_gens") or []
         root = os.path.normpath(o.preview.root)
@@ -289,6 +312,7 @@ class AiEditPipeline:
         o.status_message.emit(tr("folder.ai_generating"))
 
         def job(worker):
+            """Chạy nền: sinh lần lượt từng ảnh được yêu cầu."""
             from cowork_local.core import image_gen
             results = []
             for prompt, rel in imgs:
@@ -314,6 +338,7 @@ class AiEditPipeline:
         worker.start()
 
     def _images_done(self, res: dict, p: dict) -> None:
+        """Ảnh đã sinh xong: ghi nội dung ra đĩa."""
         o = self._owner
         self.worker = None
         o.set_busy(False)
@@ -329,6 +354,7 @@ class AiEditPipeline:
             o.preview.open_file(created[0], reset_ai=False)
 
     def _finalize_apply(self, p: dict, images_done: bool = False) -> None:
+        """Ghi nội dung đã được duyệt xuống đĩa và làm mới khung xem."""
         o = self._owner
         content = p.get("content")
         target = p.get("target")
@@ -352,6 +378,7 @@ class AiEditPipeline:
         o.flag_done()
 
     def discard(self) -> None:
+        """Bỏ bản đề xuất đang chờ, không chạm vào tệp."""
         o = self._owner
         self.pending = None
         o.show_confirm_row(False)
@@ -361,6 +388,7 @@ class AiEditPipeline:
         o.maybe_dequeue()   # discarding resolves the gate → run the next queued edit
 
     def _failed(self, err, bubble) -> None:
+        """Lượt sửa lỗi: hiện lỗi trong bong bóng và mở khoá lại panel."""
         o = self._owner
         self.worker = None
         bubble.set_markdown(tr("folder.ai_error", err=err))
diff --git a/presentation/folder/ai_file_editor_dialog.py b/presentation/folder/ai_file_editor_dialog.py
index 7b5c4b1..7e06cce 100644
--- a/presentation/folder/ai_file_editor_dialog.py
+++ b/presentation/folder/ai_file_editor_dialog.py
@@ -49,6 +49,10 @@ class AiFileEditorDialog(QWidget):
     badge_changed = Signal(str)   # "" | " ⏳" | " ✓" — the shell mirrors this onto its toggle button
 
     def __init__(self, ctx, preview, cowork=None, parent=None):
+        """Hộp thoại sửa tệp bằng AI.
+
+        ``resolver`` dựng sau, vì nó cần chính ô chọn model mà hàm này mới tạo.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self.preview = preview
@@ -118,6 +122,7 @@ class AiFileEditorDialog(QWidget):
         self.retranslate()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._ai_title.setText(tr("folder.ai_edit"))
         self.ai_input.setPlaceholderText(tr("folder.ai_placeholder"))
         self.ai_send_btn.setText(tr("folder.ai_send"))
@@ -161,6 +166,7 @@ class AiFileEditorDialog(QWidget):
 
     # ---- send / queue -------------------------------------------------------- #
     def _ai_send(self) -> None:
+        """Gửi một yêu cầu sửa; chưa chọn thư mục làm việc thì báo lỗi ngay."""
         if not self.preview.root:
             self.ai_chat.add_error(tr("folder.ai_no_file"))
             return
@@ -179,6 +185,7 @@ class AiFileEditorDialog(QWidget):
         self.pipeline.start(instruction)
 
     def _update_queue_status(self) -> None:
+        """Cập nhật dòng trạng thái theo số yêu cầu còn xếp hàng."""
         n = len(self._ai_queue)
         if n:
             self._ai_status.setText("⏳ " + tr("folder.ai_status_running")
@@ -197,6 +204,7 @@ class AiFileEditorDialog(QWidget):
 
     # ---- pipeline callbacks (see ai_edit_pipeline.py) ------------------------- #
     def set_busy(self, busy: bool) -> None:
+        """Khoá/mở ô nhập và nút gửi trong lúc một lượt sửa đang chạy."""
         self.ai_input.setEnabled(not busy)
         self.ai_send_btn.setEnabled(not busy)
         if busy:
@@ -219,9 +227,11 @@ class AiFileEditorDialog(QWidget):
         self.badge_changed.emit(" ✓")
 
     def show_confirm_row(self, visible: bool) -> None:
+        """Hiện/ẩn hàng nút Áp dụng · Huỷ cho bản đề xuất đang chờ."""
         self._ai_confirm_row.setVisible(visible)
 
     def set_review_status(self, text: str, color) -> None:
+        """Đặt dòng trạng thái kèm màu (xanh khi xong, đỏ khi lỗi)."""
         self._ai_status.setText(text)
         if color:
             self._ai_status.setStyleSheet(f"color:{color};")
diff --git a/presentation/folder/code_editor.py b/presentation/folder/code_editor.py
index 0f5de3e..d131938 100644
--- a/presentation/folder/code_editor.py
+++ b/presentation/folder/code_editor.py
@@ -17,6 +17,7 @@ _MAX_HIGHLIGHT_CHARS = 300_000     # skip colouring huge files (keeps typing sna
 
 # ── VS-Code-Dark+-ish token palette ────────────────────────────────────────
 def _fmt(color: str, *, italic: bool = False, bold: bool = False) -> QTextCharFormat:
+    """Dựng một định dạng ký tự cho bộ tô màu cú pháp."""
     f = QTextCharFormat()
     f.setForeground(QColor(color))
     if italic:
@@ -31,6 +32,11 @@ class PygmentsHighlighter(QSyntaxHighlighter):
     full text (debounced) so multi-line strings/comments colour correctly."""
 
     def __init__(self, document):
+        """Tô màu cú pháp bằng Pygments.
+
+        Tô lại sau một nhịp trễ (``QTimer`` chạy một lần) thay vì ngay mỗi phím: gõ
+        nhanh trong file lớn mà tô đồng bộ thì giao diện khựng.
+        """
         super().__init__(document)
         from pygments.lexers.special import TextLexer
         self._lexer = TextLexer(stripnl=False)
@@ -44,6 +50,7 @@ class PygmentsHighlighter(QSyntaxHighlighter):
 
     @staticmethod
     def _build_rules():
+        """Dựng bảng ánh xạ loại token của Pygments sang màu theo theme đang dùng."""
         from pygments.token import (
             Comment, Error, Keyword, Name, Number, Operator, Punctuation, String,
         )
@@ -67,6 +74,7 @@ class PygmentsHighlighter(QSyntaxHighlighter):
         ]
 
     def set_filename(self, filename: str, text: str = "") -> None:
+        """Chọn bộ phân tích cú pháp theo đuôi tệp; không nhận ra thì tắt tô màu."""
         from pygments.lexers import get_lexer_for_filename, guess_lexer
         from pygments.lexers.special import TextLexer
         from pygments.util import ClassNotFound
@@ -80,12 +88,18 @@ class PygmentsHighlighter(QSyntaxHighlighter):
         self._retokenize()
 
     def _fmt_for(self, tok):
+        """Định dạng của một token; leo dần lên token cha cho tới khi khớp một luật."""
         for ttype, fmt in self._rules:
             if tok in ttype:
                 return fmt
         return None
 
     def _retokenize(self) -> None:
+        """Phân tích lại toàn bộ tài liệu và ghi nhớ định dạng cho từng dòng.
+
+        Pygments phân tích theo cả tệp chứ không theo từng dòng, nên không thể
+        tô đúng nếu chỉ nhìn một dòng — ví dụ chuỗi nhiều dòng hay khối chú thích.
+        """
         from pygments import lex
         text = self.document().toPlainText()
         self._ranges = []
@@ -99,6 +113,7 @@ class PygmentsHighlighter(QSyntaxHighlighter):
         self.rehighlight()
 
     def highlightBlock(self, text: str) -> None:  # noqa: N802 - Qt override
+        """Áp định dạng đã tính sẵn cho một dòng. Qt gọi hàm này cho từng dòng hiện trên màn."""
         if not self._ranges:
             return
         bstart = self.currentBlock().position()
@@ -113,14 +128,18 @@ class PygmentsHighlighter(QSyntaxHighlighter):
 
 
 class _LineNumbers(QWidget):
+    """Máng số dòng vẽ bên trái ô soạn thảo."""
     def __init__(self, editor):
+        """Dải số dòng bên trái ô soạn mã."""
         super().__init__(editor)
         self._editor = editor
 
     def sizeHint(self) -> QSize:
+        """Bề rộng máng số dòng, do ô soạn thảo tính theo số chữ số của dòng cuối."""
         return QSize(self._editor.line_number_width(), 0)
 
     def paintEvent(self, event):  # noqa: N802
+        """Nhờ ô soạn thảo vẽ — nó mới biết dòng nào đang hiện ở đâu."""
         self._editor.paint_line_numbers(event)
 
 
@@ -129,6 +148,11 @@ class CodeEditor(QPlainTextEdit):
     the Sublime/VS-Code look for viewing & editing source files."""
 
     def __init__(self):
+        """Ô soạn mã: phông đều, không tự xuống dòng, tab rộng 4 ký tự.
+
+        Không tự xuống dòng là cố ý — mã bị bẻ dòng thì lệch thụt đầu dòng và khó
+        đọc hơn là phải cuộn ngang.
+        """
         super().__init__()
         self.setObjectName("codeEditor")
         self.setLineWrapMode(QPlainTextEdit.NoWrap)
@@ -144,13 +168,16 @@ class CodeEditor(QPlainTextEdit):
         self._update_gutter_width()
 
     def line_number_width(self) -> int:
+        """Bề rộng cần cho máng số dòng, tính theo số chữ số của dòng cuối cùng."""
         digits = max(2, len(str(max(1, self.blockCount()))))
         return 12 + self.fontMetrics().horizontalAdvance("9") * digits
 
     def _update_gutter_width(self) -> None:
+        """Chừa lề trái đúng bằng bề rộng máng số dòng."""
         self.setViewportMargins(self.line_number_width(), 0, 0, 0)
 
     def _on_update_request(self, rect, dy: int) -> None:
+        """Cuộn hoặc vẽ lại vùng nào thì máng số dòng cuộn/vẽ lại đúng vùng đó."""
         if dy:
             self._gutter.scroll(0, dy)
         else:
@@ -159,11 +186,13 @@ class CodeEditor(QPlainTextEdit):
             self._update_gutter_width()
 
     def resizeEvent(self, event):  # noqa: N802
+        """Đổi kích thước thì đặt lại hình chữ nhật của máng số dòng."""
         super().resizeEvent(event)
         cr = self.contentsRect()
         self._gutter.setGeometry(QRect(cr.left(), cr.top(), self.line_number_width(), cr.height()))
 
     def paint_line_numbers(self, event) -> None:
+        """Vẽ số của các dòng đang hiện trên màn, bỏ qua dòng bị gập hoặc nằm ngoài khung."""
         p = current_palette()
         painter = QPainter(self._gutter)
         painter.fillRect(event.rect(), QColor(p.code_gutter_bg))
@@ -183,6 +212,7 @@ class CodeEditor(QPlainTextEdit):
             num += 1
 
     def load_file(self, path: str, text: str) -> None:
+        """Nạp nội dung tệp vào ô soạn thảo và bật tô màu theo đuôi tệp."""
         self.setPlainText(text)
         self._highlighter.set_filename(path, text)
 
diff --git a/presentation/folder/document_preview_manager.py b/presentation/folder/document_preview_manager.py
index a1af89e..4af891f 100644
--- a/presentation/folder/document_preview_manager.py
+++ b/presentation/folder/document_preview_manager.py
@@ -57,6 +57,11 @@ class DocumentPreviewManager(QWidget):
     ai_reset_requested = Signal()   # a DIFFERENT file was opened by the user
 
     def __init__(self, root: str, parent=None):
+        """Khung xem tài liệu.
+
+        Mọi lượt đọc tệp đi qua ``FileWorkspaceService`` nên không thoát ra ngoài
+        thư mục gốc, kể cả khi đường dẫn có ``..``.
+        """
         super().__init__(parent)
         self._root = root
         self._file_service = FileWorkspaceService(WorkspaceSession.unscoped(Path(root)))
@@ -123,6 +128,7 @@ class DocumentPreviewManager(QWidget):
         self.retranslate()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho các nút và ô trống."""
         self.save_btn.setText(tr("folder.save"))
         self.ext_btn.setText(tr("folder.open_external"))
         if not self._current_file:
@@ -130,23 +136,28 @@ class DocumentPreviewManager(QWidget):
         self._retranslate_mode_btn()
 
     def _retranslate_mode_btn(self) -> None:
+        """Nhãn nút chuyển chế độ đổi theo trạng thái: đang xem thì ghi "Sửa" và ngược lại."""
         self.mode_btn.setText(tr("folder.edit") if not self.mode_btn.isChecked()
                               else tr("folder.preview"))
 
     # ---- public API used by the shell / AI panel --------------------------- #
     @property
     def current_file(self) -> Optional[str]:
+        """Đường dẫn tệp đang mở; ``None`` nếu chưa mở tệp nào."""
         return self._current_file
 
     @property
     def edit_kind(self) -> Optional[str]:
+        """Loại nội dung đang sửa ('pptx', 'html', 'text'…); ``None`` nếu đang chỉ xem."""
         return self._edit_kind
 
     @property
     def root(self) -> str:
+        """Thư mục gốc mà mọi thao tác ghi phải nằm bên trong."""
         return self._root
 
     def set_root(self, root: str) -> None:
+        """Đổi thư mục gốc và dựng lại dịch vụ ghi tệp gắn với phạm vi mới."""
         self._root = root
         self._file_service = FileWorkspaceService(WorkspaceSession.unscoped(Path(root)))
 
@@ -155,6 +166,13 @@ class DocumentPreviewManager(QWidget):
         # (reset_ai=False when the AI itself just CREATED this file — keep
         # that chat). Whether/how to reset is the AI panel's own business —
         # this class only announces that a genuine file switch happened.
+        """Mở một tệp, tự chọn cách hiển thị theo đuôi và kích thước.
+
+        Thứ tự ưu tiên: ảnh → HTML → PowerPoint → Excel → tài liệu Office → nhị
+        phân (quá lớn hoặc không phải văn bản) → mã nguồn. Đổi sang tệp KHÁC thì
+        báo cho panel AI biết để nó bắt đầu hội thoại mới; ``reset_ai=False`` dùng
+        khi chính AI vừa tạo ra tệp này — giữ nguyên đoạn chat đang dở.
+        """
         if reset_ai and path != self._current_file:
             self.ai_reset_requested.emit()
         self._current_file = path
@@ -206,6 +224,7 @@ class DocumentPreviewManager(QWidget):
         return False
 
     def save(self) -> None:
+        """Lưu nội dung đang sửa xuống tệp; pptx ghi ngược vào bản trình chiếu."""
         if not self._current_file:
             return
         try:
@@ -261,6 +280,7 @@ class DocumentPreviewManager(QWidget):
         return dest
 
     def open_external(self) -> None:
+        """Mở tệp đang xem bằng ứng dụng mặc định của hệ điều hành."""
         if self._current_file:
             from cowork_local.ui.osutil import open_location
             open_location(self._current_file)
@@ -278,6 +298,7 @@ class DocumentPreviewManager(QWidget):
     # ---- simple renderers (HTML/PPTX/Excel/PDF/office live in
     # office_document_renderer.py) --------------------------------------------- #
     def _show_code(self, path: str) -> None:
+        """Hiện tệp trong ô soạn thảo có tô màu cú pháp, cho phép sửa và lưu."""
         text = read_text(path)
         self.editor.setReadOnly(False)
         self.editor.load_file(path, text)
@@ -285,6 +306,7 @@ class DocumentPreviewManager(QWidget):
         self.stack.setCurrentWidget(self.editor)
 
     def _show_image(self, path: str) -> None:
+        """Hiện ảnh; ảnh hỏng hoặc không đọc được thì rơi về khung nhị phân."""
         from PySide6.QtGui import QPixmap
         pix = QPixmap(path)
         if pix.isNull():
@@ -296,6 +318,7 @@ class DocumentPreviewManager(QWidget):
         self.stack.setCurrentWidget(self._img_scroll)
 
     def _show_binary(self, path: str) -> None:
+        """Hiện thông báo "tệp nhị phân" kèm nút mở bằng ứng dụng ngoài."""
         self._placeholder.setText(tr("folder.binary_file"))
         self.ext_btn.setVisible(True)
         self.stack.setCurrentWidget(self._placeholder)
diff --git a/presentation/folder/folder_tab.py b/presentation/folder/folder_tab.py
index 65714ab..2fffcda 100644
--- a/presentation/folder/folder_tab.py
+++ b/presentation/folder/folder_tab.py
@@ -30,6 +30,7 @@ class FolderTab(QWidget):
     status_message = Signal(str)
 
     def __init__(self, ctx: AppContext, cowork=None):
+        """Ghép ba phần của tab Thư mục: cây tệp, khung xem và terminal."""
         super().__init__()
         self.ctx = ctx
         self._root = str(ctx.config.cowork_output_dir())
@@ -90,6 +91,11 @@ class FolderTab(QWidget):
 
     # ---- public API ---------------------------------------------------------
     def set_root(self, path: str) -> None:
+        """Đổi thư mục gốc của cả ba widget con.
+
+        ``WorkspaceFileTree`` lặng lẽ từ chối đường dẫn không hợp lệ, nên chỉ lan
+        sang khung xem và terminal khi cây thật sự đã nhận.
+        """
         self.tree.set_root(path)
         # WorkspaceFileTree silently no-ops on an invalid path (same guard
         # the original single-class _root setter had) — mirror that here by
@@ -100,6 +106,7 @@ class FolderTab(QWidget):
             self.terminal.set_cwd(path)
 
     def _toggle_ai_panel(self) -> None:
+        """Gập/mở panel AI-Edit; mở ra thì báo cho panel biết để nó nạp model lần đầu."""
         show = self.ai_btn.isChecked()
         self.ai_panel.setVisible(show)
         if show:
@@ -107,9 +114,11 @@ class FolderTab(QWidget):
             self.ai_panel.on_opened()
 
     def _on_ai_badge_changed(self, suffix: str) -> None:
+        """Cập nhật huy hiệu trên nút AI-Edit (số việc đang chờ)."""
         self.ai_btn.setText(tr("folder.ai_edit") + suffix)
 
     def _retranslate(self) -> None:
+        """Chuyển lệnh dịch lại xuống cho cả ba widget con."""
         self.tree.retranslate()
         self.preview.retranslate()
         self.ai_panel.retranslate()
diff --git a/presentation/folder/office_document_renderer.py b/presentation/folder/office_document_renderer.py
index c9494ab..9e6f09e 100644
--- a/presentation/folder/office_document_renderer.py
+++ b/presentation/folder/office_document_renderer.py
@@ -44,6 +44,11 @@ class OfficeDocumentRenderer:
     """
 
     def __init__(self, owner) -> None:
+        """Bộ hiện tài liệu Office.
+
+        Có cache PDF vì mỗi lần chuyển đổi phải gọi LibreOffice — xem lại cùng một
+        tệp mà chuyển lại từ đầu thì chờ vài giây mỗi lượt.
+        """
         self._owner = owner
         self._engine = None
         self._pdf_view = None
@@ -54,6 +59,7 @@ class OfficeDocumentRenderer:
         self._xlsx_view = None
 
     def show_html(self, path: str, mode_preview: bool) -> None:
+        """Hiện tệp HTML: xem đã dựng hình hoặc sửa mã nguồn, tuỳ ``mode_preview``."""
         o = self._owner
         o._edit_kind = "html"
         o.mode_btn.setVisible(True)
@@ -111,6 +117,7 @@ class OfficeDocumentRenderer:
         return self._engine
 
     def toggle_edit_mode(self) -> None:
+        """Lật giữa Xem và Sửa cho tệp đang mở (HTML và PowerPoint)."""
         o = self._owner
         if not o.current_file:
             return
@@ -194,9 +201,14 @@ class OfficeDocumentRenderer:
         src, out_dir = path, self._pdf_tmp
 
         def job(worker):
+            """Chạy nền: chuyển tài liệu Office sang PDF bằng LibreOffice."""
             return {"src": src, "mtime": mtime, "pdf": convert_to_pdf(src, out_dir)}
 
         def done(result):
+            """Hiện PDF vừa chuyển và ghi vào bộ nhớ đệm theo (đường dẫn, thời điểm sửa).
+
+            Bỏ kết quả nếu người dùng đã chuyển sang tệp khác trong lúc chờ chuyển đổi.
+            """
             if result.get("src") != o.current_file:
                 return   # user moved on to another file
             pdf = result.get("pdf")
@@ -213,6 +225,9 @@ class OfficeDocumentRenderer:
         worker.start()
 
     def _ensure_pdf_view(self):
+        """Dựng khung xem PDF một lần duy nhất; không có ``QtPdf`` thì trả ``None``
+        để chỗ gọi rơi về cách hiện văn bản thuần.
+        """
         if not HAS_PDF:
             return None
         if self._pdf_view is None:
@@ -230,6 +245,7 @@ class OfficeDocumentRenderer:
         return self._pdf_view
 
     def _render_pdf(self, pdf_path: str) -> None:
+        """Nạp và hiện một tệp PDF; thiếu ``QtPdf`` thì rơi về trích văn bản."""
         view = self._ensure_pdf_view()
         if view is None:
             self.show_document_text(pdf_path)
@@ -238,6 +254,10 @@ class OfficeDocumentRenderer:
         self._owner.stack.setCurrentWidget(view)
 
     def show_document_text(self, path: str) -> None:
+        """Cách dự phòng cuối: trích văn bản từ tài liệu và hiện dưới dạng chữ thuần.
+
+        Dùng khi không có LibreOffice để chuyển PDF, hoặc không có khung xem PDF.
+        """
         from cowork_local.core.doc_extract import extract_text
         o = self._owner
         try:
diff --git a/presentation/folder/workspace_file_tree.py b/presentation/folder/workspace_file_tree.py
index b7c0f63..1482baa 100644
--- a/presentation/folder/workspace_file_tree.py
+++ b/presentation/folder/workspace_file_tree.py
@@ -29,6 +29,7 @@ class WorkspaceFileTree(QWidget):
     root_changed = Signal(str)    # absolute path of the new root
 
     def __init__(self, initial_root: str, parent=None):
+        """Cây tệp của thư mục làm việc, có ô đường dẫn ở trên làm tiêu đề màn hình."""
         super().__init__(parent)
         self._root = initial_root
 
@@ -65,14 +66,20 @@ class WorkspaceFileTree(QWidget):
         self.retranslate()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._open_btn.setToolTip(tr("folder.path_placeholder"))
         self._open_btn.setText(tr("folder.open_folder"))
 
     @property
     def root(self) -> str:
+        """Thư mục gốc đang hiện."""
         return self._root
 
     def set_root(self, path: str) -> None:
+        """Đổi thư mục gốc; đường dẫn rỗng hoặc không tồn tại thì BỎ QUA lặng lẽ.
+
+        Chỗ gọi dựa vào việc ``root`` không đổi để biết cây đã từ chối đường dẫn.
+        """
         p = str(path or "").strip()
         if not p or not os.path.isdir(p):
             return
@@ -84,11 +91,13 @@ class WorkspaceFileTree(QWidget):
         self.root_changed.emit(p)
 
     def _pick_root(self) -> None:
+        """Mở hộp thoại chọn thư mục gốc."""
         chosen = QFileDialog.getExistingDirectory(self, tr("folder.open_folder"), self._root)
         if chosen:
             self.set_root(chosen)
 
     def _on_tree_clicked(self, index) -> None:
+        """Bấm vào một mục: là tệp thì phát tín hiệu mở, là thư mục thì để cây tự bung."""
         path = self.model.filePath(index)
         if path and os.path.isfile(path):
             self.file_selected.emit(path)
diff --git a/presentation/graph/graph_export.py b/presentation/graph/graph_export.py
new file mode 100644
index 0000000..9d490a9
--- /dev/null
+++ b/presentation/graph/graph_export.py
@@ -0,0 +1,81 @@
+"""Xuất khung đồ thị đang xem ra file PNG — tách khỏi ``graph_renderer.py``.
+
+GraphRAG có hai khung xem: cảnh Qt 2D và trang D3 chạy trong WebEngine. Hai
+khung ấy chụp ảnh theo hai cách hoàn toàn khác nhau (``QWidget.grab()`` so
+với một lượt gọi JavaScript trả về data URL), nên chỗ này gom cả hai lại sau
+một hàm duy nhất và tự chọn đường đi.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Callable, Optional
+
+from PySide6.QtWidgets import QFileDialog, QWidget
+
+from cowork_local.i18n import tr
+
+#: Bên gọi truyền vào để hiện kết quả trên thanh trạng thái.
+StatusFn = Callable[[str], None]
+
+
+def ask_export_path(parent: QWidget) -> str:
+    """Hỏi người dùng nơi lưu ảnh; trả về '' nếu họ bấm Huỷ."""
+    path, _ = QFileDialog.getSaveFileName(
+        parent, tr("structure.export_title"), "structure-graph.png", "PNG (*.png)")
+    return path or ""
+
+
+def export_widget_grab(widget: QWidget, path: str, status: StatusFn) -> None:
+    """Chụp thẳng widget đang hiện ra PNG.
+
+    Đây cũng là đường lui khi xuất từ D3 thất bại: chụp widget luôn cho ra
+    một tấm ảnh, dù không sắc nét bằng bản vẽ vector của D3.
+    """
+    if widget.grab().save(path, "PNG"):
+        status(tr("structure.export_done", path=path))
+    else:
+        status(tr("structure.export_failed", err="grab() returned no image"))
+
+
+def export_d3_png(web, path: str, fallback: QWidget, status: StatusFn) -> None:
+    """Xuất PNG từ trang D3 bằng cách nhờ chính trang đó vẽ ra data URL.
+
+    ``runJavaScript`` chạy bất đồng bộ nên kết quả về trong hàm gọi lại. Mọi
+    đường hỏng — trang chưa nạp xong, ``window.exportPng`` không tồn tại,
+    chuỗi trả về không phải data URL — đều quay sang chụp widget, để người
+    dùng bấm Xuất vẫn luôn nhận được một file thay vì im lặng không có gì.
+    """
+    def on_result(data_url) -> None:
+        """Nhận data URL từ trang D3 và ghi ra file; hỏng ở bất cứ đâu thì quay sang
+        chụp widget.
+        """
+        if not isinstance(data_url, str) or "," not in data_url:
+            export_widget_grab(fallback, path, status)
+            return
+        try:
+            with open(path, "wb") as f:
+                f.write(base64.b64decode(data_url.split(",", 1)[1]))
+            status(tr("structure.export_done", path=path))
+        except (OSError, ValueError) as exc:
+            status(tr("structure.export_failed", err=str(exc)))
+
+    web.page().runJavaScript("window.exportPng ? window.exportPng() : ''", on_result)
+
+
+def export_png(parent: QWidget, showing: QWidget, web: Optional[object],
+               is_web_visible: bool, status: StatusFn) -> None:
+    """Hỏi đường dẫn rồi xuất khung ĐANG hiện — D3 hay cảnh Qt tuỳ tab đang mở.
+
+    Chỉ dùng đường D3 khi trang D3 thật sự đang hiển thị; đang xem cảnh Qt mà
+    lại chụp D3 thì ảnh ra không khớp với thứ người dùng nhìn thấy.
+    """
+    path = ask_export_path(parent)
+    if not path:
+        return
+    if web is not None and is_web_visible:
+        export_d3_png(web, path, showing, status)
+    else:
+        export_widget_grab(showing, path, status)
+
+
+__all__ = ["export_png", "export_d3_png", "export_widget_grab", "ask_export_path"]
diff --git a/presentation/graph/graph_messages_view.py b/presentation/graph/graph_messages_view.py
index 1591fd8..c6e2f03 100644
--- a/presentation/graph/graph_messages_view.py
+++ b/presentation/graph/graph_messages_view.py
@@ -22,7 +22,15 @@ from cowork_local.i18n import tr
 
 
 class GraphMessagesView:
+    """Tab "Tin nhắn" của GraphRAG: cây hội thoại gom theo ngày, bấm vào xem JSON.
+
+    Một helper thuần (không phải widget) do ``GraphRenderer`` sở hữu; nó tự dựng
+    cây và đưa vào stack dùng chung của chủ sở hữu.
+    """
     def __init__(self, owner) -> None:
+        """Dựng cây tin nhắn và đưa vào stack dùng chung của chủ sở hữu — helper thuần,
+        không phải widget độc lập.
+        """
         self._owner = owner
         self.widget = QTreeWidget()
         self.widget.setHeaderHidden(True)
@@ -76,6 +84,9 @@ class GraphMessagesView:
             day_item.setExpanded(True)
 
     def _show_msg_json(self, item, _col: int = 0) -> None:
+        """Bấm một hội thoại trong cây: hiện toàn bộ nội dung của nó dưới dạng JSON đã
+        thoát HTML ở khung chi tiết.
+        """
         import html
         import json
 
diff --git a/presentation/graph/graph_qa_widget.py b/presentation/graph/graph_qa_widget.py
index fcd9156..3b0437c 100644
--- a/presentation/graph/graph_qa_widget.py
+++ b/presentation/graph/graph_qa_widget.py
@@ -41,6 +41,11 @@ class GraphQaWidget(QWidget):
     collapse_changed = Signal(bool)   # so the shell can resize its own splitter
 
     def __init__(self, ctx, renderer, parent=None):
+        """Panel Hỏi đáp bên phải màn GraphRAG.
+
+        Có cache trích xuất vì cùng một node hay bị hỏi lại nhiều lần trong một
+        phiên, mà mỗi lần trích lại phải đọc tệp.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._renderer = renderer
@@ -97,6 +102,7 @@ class GraphQaWidget(QWidget):
         self.retranslate()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, ô hỏi và tooltip."""
         self._collapse_btn.setToolTip(tr("structure.collapse_agent_tooltip"))
         self._label.setText(tr("structure.agent_header"))
         self.ask_edit.setPlaceholderText(tr("structure.ask_placeholder"))
@@ -107,25 +113,30 @@ class GraphQaWidget(QWidget):
 
     # ---- collapse ------------------------------------------------------------- #
     def _set_collapsed(self, collapsed: bool) -> None:
+        """Gập/mở panel hỏi-đáp và báo ra ngoài để vỏ chỉnh lại splitter."""
         self._panel.setVisible(not collapsed)
         self._strip.setVisible(collapsed)
         self.collapse_changed.emit(collapsed)
 
     # ---- reacting to the renderer ----------------------------------------------- #
     def _on_node_selected(self, data) -> None:
+        """Chọn một node trên đồ thị: hiện chi tiết của node đó ở khung dưới."""
         self.detail.setPlainText(f"[{data.kind.upper()}] {data.label}\n\n{data.detail}")
         self._detail_mode = "node"
 
     def _show_raw_json(self, html_text: str) -> None:
+        """Hiện JSON thô của một hội thoại được chọn ở tab Tin nhắn."""
         self.detail.setHtml(html_text)
 
     def _preserve_answer(self) -> None:
+        """Vẽ lại câu trả lời AI sau khi khung chi tiết bị dùng cho việc khác — nếu"""
         if self._detail_mode == "answer" and self._answer.strip():
             self._render_answer()
 
     # ---- Q&A -------------------------------------------------------------------- #
     @staticmethod
     def _graph_context(graph) -> str:
+        """Tóm tắt đồ thị thành văn bản gọn để nhét vào prompt: gom node theo loại,"""
         from collections import defaultdict
         by_kind = defaultdict(list)
         for n in graph.nodes:
@@ -143,6 +154,7 @@ class GraphQaWidget(QWidget):
         return "\n".join(lines)[:7000]
 
     def _matched_sources(self, text: str):
+        """Các node có tên xuất hiện trong câu trả lời — dùng để gắn link nguồn kiểm"""
         graph = self._renderer.graph
         if graph is None or not text:
             return []
@@ -176,6 +188,7 @@ class GraphQaWidget(QWidget):
         return text
 
     def _render_answer(self) -> None:
+        """Vẽ câu trả lời dạng markdown kèm danh sách nguồn bấm mở được."""
         text = self._answer
         sources = self._matched_sources(text)
         if sources:
@@ -189,6 +202,9 @@ class GraphQaWidget(QWidget):
         self.detail.setMarkdown(text)
 
     def _on_detail_link(self, url: QUrl) -> None:
+        """Bấm một link trong khung chi tiết: là tệp thì mở tệp, còn lại mở bằng trình
+        duyệt.
+        """
         if url.isLocalFile():
             p = url.toLocalFile()
             if Path(p).is_file():
@@ -197,6 +213,7 @@ class GraphQaWidget(QWidget):
                 open_folder(p)
 
     def _ask(self) -> None:
+        """Gửi câu hỏi về đồ thị tới model, chạy ở luồng nền."""
         question = self.ask_edit.text().strip()
         if not question:
             return
@@ -225,6 +242,7 @@ class GraphQaWidget(QWidget):
         selected_context = self._selection_context(selected_nodes, graph)
 
         def job(worker: AgentWorker):
+            """Chạy nền: ghép ngữ cảnh đồ thị + nội dung tệp đã trích rồi gọi model."""
             provider = self.ctx.build_active_provider()
             system = self._system_prompt(skill_prefix, active_project_id)
             user_content = f"Graph context:\n{context}"
@@ -261,6 +279,7 @@ class GraphQaWidget(QWidget):
 
     @staticmethod
     def _selection_context(selected_nodes, graph) -> str:
+        """Phần ngữ cảnh thêm cho các node người dùng đang chọn — câu hỏi "cái này là"""
         if not selected_nodes:
             return ""
         node_lines = []
@@ -284,6 +303,7 @@ class GraphQaWidget(QWidget):
 
     @staticmethod
     def _system_prompt(skill_prefix: str, active_project_id: str) -> str:
+        """Prompt hệ thống cho khung hỏi-đáp."""
         system = ("You answer questions about a code/document knowledge graph. Use the provided "
                   "graph context AND the extracted file contents to retrieve, synthesize and "
                   "explain the answer. Be concise. Answer ONLY from what is provided (graph "
@@ -321,6 +341,7 @@ class GraphQaWidget(QWidget):
         return system
 
     def _on_ask_event(self, ev: dict) -> None:
+        """Nhận từng mẩu trả lời đang phát dần và vẽ dần vào khung chi tiết."""
         if ev.get("type") == "text":
             if self._answer == "":
                 self.detail.clear()
@@ -330,6 +351,7 @@ class GraphQaWidget(QWidget):
     def _on_ask_done(self, result: dict) -> None:
         # Keep the (temporary) extracted content so repeated questions reuse
         # it without re-extracting — dropped when leaving the tab.
+        """Trả lời xong: giữ lại nội dung tệp đã trích để câu hỏi sau không phải trích"""
         if isinstance(result, dict):
             self._extract_cache.update(result.get("extracted", {}) or {})
         self._render_answer()
@@ -352,6 +374,7 @@ class GraphQaWidget(QWidget):
         return out
 
     def _extract_tmp_dir(self) -> Path:
+        """Thư mục tạm chứa nội dung tệp đã trích, tạo lười ở lần cần đầu tiên."""
         if self._extract_dir is None:
             import tempfile
             from cowork_local.config import CONFIG_DIR
diff --git a/presentation/graph/graph_renderer.py b/presentation/graph/graph_renderer.py
index 45a046b..5b1dcb6 100644
--- a/presentation/graph/graph_renderer.py
+++ b/presentation/graph/graph_renderer.py
@@ -13,7 +13,6 @@ AI-edit panel either.
 """
 from __future__ import annotations
 
-import math
 from pathlib import Path
 from typing import List, Optional
 
@@ -26,7 +25,9 @@ from PySide6.QtWidgets import (
 
 from cowork_local.core.worker import AgentWorker
 from cowork_local.i18n import on_language_changed, tr
+from cowork_local.presentation.graph import graph_export
 from cowork_local.presentation.graph.graph_messages_view import GraphMessagesView
+from cowork_local.presentation.graph.graph_scene_builder import build_scene
 from cowork_local.presentation.graph.graph_scene_items import _Bridge, _Edge, _GraphView, _Node
 from cowork_local.presentation.shared import HAS_WEB_ENGINE
 from cowork_local.state import AppContext
@@ -35,6 +36,7 @@ from cowork_local.ui.icons import icon
 
 
 class GraphRenderer(QWidget):
+    """Nửa "đồ thị" của màn GraphRAG: thanh công cụ, khung xem và vòng đời quét."""
     status_message = Signal(str)
     node_selected = Signal(object)   # a node's .data, whenever the scene selection changes
     graph_rendered = Signal()        # a scan just finished rendering (fresh OR re-fit)
@@ -42,6 +44,12 @@ class GraphRenderer(QWidget):
     project_changed = Signal()       # a DIFFERENT project was selected (or cleared)
 
     def __init__(self, ctx: AppContext):
+        """Dựng thanh công cụ, khung xem 2D và chỗ chờ cho khung D3.
+
+        Khung D3 KHÔNG được dựng ở đây: ``QWebEngineView`` mất vài trăm mili giây
+        để khởi tạo, mà phần lớn người dùng mở màn này chỉ để xem cảnh Qt. Nó được
+        dựng muộn trong :meth:`_ensure_web`.
+        """
         super().__init__()
         self.ctx = ctx
         self._worker: Optional[AgentWorker] = None
@@ -118,6 +126,7 @@ class GraphRenderer(QWidget):
         on_language_changed(self._retranslate)
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho thanh công cụ và tên tab."""
         self.path_edit.setPlaceholderText(tr("structure.path_placeholder"))
         self._pick_btn.setText(tr("structure.browse"))
         self._scan_btn.setText(tr("structure.scan"))
@@ -131,17 +140,23 @@ class GraphRenderer(QWidget):
     # ---- public read API for GraphQaWidget ----------------------------------- #
     @property
     def graph(self):
+        """Đồ thị đã quét gần nhất; ``None`` nếu chưa quét lần nào."""
         return self._graph
 
     @property
     def active_project_id(self) -> str:
+        """Id dự án đang chọn trong bộ chọn; '' nếu chưa chọn."""
         return self._active_project_id
 
     def selected_node_data(self) -> list:
+        """Dữ liệu của các node đang được chọn trên cảnh — panel Hỏi đáp đọc cái này
+        để biết người dùng đang hỏi về cái gì.
+        """
         return [item.data for item in self.scene.selectedItems() if isinstance(item, _Node)]
 
     # ---- project sandbox lock ------------------------------------------------- #
     def _refresh_project_combo(self) -> None:
+        """Nạp lại danh sách project vào bộ chọn, giữ nguyên project đang chọn."""
         from cowork_local.core.projects import list_projects
 
         keep = self._active_project_id
@@ -157,6 +172,7 @@ class GraphRenderer(QWidget):
         self.project_combo.blockSignals(False)
 
     def set_project(self, project_id: str) -> None:
+        """Khoá phạm vi quét vào một project (chuỗi rỗng là bỏ khoá)."""
         pid = project_id or ""
         self._refresh_project_combo()
         target = self.project_combo.findData(pid)
@@ -168,6 +184,7 @@ class GraphRenderer(QWidget):
             self.project_combo.setCurrentIndex(target)
 
     def _on_project_changed(self, _idx: int) -> None:
+        """Áp trạng thái khoá: đường dẫn chuyển sang chỉ đọc và trỏ vào thư mục"""
         from cowork_local.core.projects import load_project
 
         pid = self.project_combo.currentData() or ""
@@ -188,11 +205,13 @@ class GraphRenderer(QWidget):
 
     # ---- helpers ---------------------------------------------------------------- #
     def _pick(self) -> None:
+        """Mở hộp thoại chọn thư mục gốc để quét."""
         chosen = QFileDialog.getExistingDirectory(self, tr("structure.pick_folder_title"), self.path_edit.text())
         if chosen:
             self.path_edit.setText(chosen)
 
     def schedule_rescan(self, path: str = "") -> None:
+        """Hẹn quét lại sau khi có thay đổi trên đĩa."""
         if self._graph is None:
             self._needs_scan = True
             return
@@ -200,6 +219,7 @@ class GraphRenderer(QWidget):
 
     # ---- Messages (by day, as JSON) — see graph_messages_view.py --------------- #
     def _on_view_tab(self, index: int) -> None:
+        """Đổi giữa tab đồ thị và tab Tin nhắn."""
         self._messages.on_view_tab(index)
 
     def _toggle_messages(self) -> None:
@@ -217,6 +237,11 @@ class GraphRenderer(QWidget):
             self._scan()
 
     def _ensure_web(self) -> None:
+        """Dựng khung D3 nếu máy có WebEngine và chưa dựng.
+
+        Gọi được nhiều lần — lần thứ hai trở đi không làm gì. Máy không có
+        WebEngine thì bỏ qua im lặng và người dùng ở lại với cảnh Qt.
+        """
         if self.web is not None or not HAS_WEB_ENGINE:
             return
         from PySide6.QtWebChannel import QWebChannel
@@ -235,6 +260,7 @@ class GraphRenderer(QWidget):
             self._render_d3()
 
     def auto_scan_and_fit(self) -> None:
+        """Vào màn GraphRAG: hiện đồ thị, chỉ quét lại khi thật sự cần."""
         self._ensure_web()
         if not self.path_edit.text().strip():
             return
@@ -251,6 +277,11 @@ class GraphRenderer(QWidget):
 
     # ---- scan --------------------------------------------------------------------- #
     def _scan(self) -> None:
+        """Quét thư mục gốc ở luồng nền rồi vẽ kết quả.
+
+        Mỗi lượt quét mang một số thứ tự ``_scan_seq``; kết quả về mà số không còn
+        khớp thì bị bỏ, để lượt quét cũ không đè lên lượt mới.
+        """
         path = self.path_edit.text().strip() or str(Path.cwd())
         mode = "files"
         use_cmem = bool(self.ctx.config.codebase_memory.get("enabled"))
@@ -263,6 +294,11 @@ class GraphRenderer(QWidget):
         self.status_message.emit(tr("structure.scanning"))
 
         def job(worker: AgentWorker):
+            """Chạy nền: dựng đồ thị từ thư mục rồi tính toạ độ.
+
+            Ưu tiên đọc từ codebase-memory nếu có sẵn — nhanh hơn nhiều so với quét lại
+            cả cây thư mục; không có thì quét trực tiếp.
+            """
             from cowork_local.core.structure_graph import (
                 build_from_codebase_memory, build_from_directory, force_layout,
             )
@@ -283,6 +319,12 @@ class GraphRenderer(QWidget):
         w.start()
 
     def _render(self, result: dict) -> None:
+        """Vẽ kết quả quét ra khung Qt 2D (và ra D3 nếu đang bật).
+
+        Lượt quét cũ về muộn thì bỏ: ``seq`` của nó không còn khớp
+        ``_scan_seq``. Không chặn ở đây thì người dùng đổi dự án nhanh sẽ thấy
+        đồ thị của dự án TRƯỚC đè lên dự án đang chọn.
+        """
         if result.get("seq") is not None and result["seq"] != self._scan_seq:
             return
         graph = result.get("graph")
@@ -291,36 +333,8 @@ class GraphRenderer(QWidget):
             return
         self._graph = graph
 
-        self.scene.clear()
-        self.scene.setBackgroundBrush(QColor(current_palette().bg))
-        self._node_items = []
-        self._edge_items = []
-        degree = {n.id: 0 for n in graph.nodes}
-        for e in graph.edges:
-            if e.source in degree:
-                degree[e.source] += 1
-            if e.target in degree:
-                degree[e.target] += 1
-        items = {}
-        sx = sy = 0.0
-        for node in graph.nodes:
-            radius = int(8 + min(20, 2.2 * math.sqrt(degree.get(node.id, 0))))
-            item = _Node(node, radius)
-            x, y = pos.get(node.id, (0, 0))
-            item.setPos(x, y)
-            self.scene.addItem(item)
-            items[node.id] = item
-            self._node_items.append(item)
-            sx += x
-            sy += y
-        for edge in graph.edges:
-            a, b = items.get(edge.source), items.get(edge.target)
-            if a and b:
-                e = _Edge(a, b, getattr(edge, "type", ""))
-                self.scene.addItem(e)
-                self._edge_items.append(e)
-        n = max(1, len(self._node_items))
-        self._centroid = QPointF(sx / n, sy / n)
+        self._node_items, self._edge_items, self._centroid = build_scene(
+            self.scene, graph, pos, current_palette().bg)
         self._fit()
 
         if self.web is not None:
@@ -332,6 +346,9 @@ class GraphRenderer(QWidget):
         self.graph_rendered.emit()
 
     def _render_d3(self) -> None:
+        """Nạp lại trang D3 từ đồ thị hiện có. Lỗi dựng HTML chỉ báo lên thanh trạng
+        thái chứ không ném ra — cảnh Qt vẫn xem được.
+        """
         if self.web is None or self._graph is None:
             return
         from cowork_local.core.d3_graph import build_html
@@ -342,12 +359,14 @@ class GraphRenderer(QWidget):
 
     # ---- native interactions ------------------------------------------------------- #
     def _on_selection(self) -> None:
+        """Chọn một node trên cảnh thì báo cho panel Hỏi đáp biết."""
         for item in self.scene.selectedItems():
             if isinstance(item, _Node):
                 self.node_selected.emit(item.data)
                 return
 
     def _fit(self) -> None:
+        """Canh toàn bộ đồ thị vừa khung nhìn."""
         if self.web is not None and self._stack.currentWidget() is self.web:
             self.web.page().runJavaScript("window.fitGraph && window.fitGraph();")
             return
@@ -356,36 +375,17 @@ class GraphRenderer(QWidget):
             self.view.fitInView(rect.adjusted(-40, -40, 40, 40), Qt.KeepAspectRatio)
 
     def _export(self) -> None:
-        path, _ = QFileDialog.getSaveFileName(
-            self, tr("structure.export_title"), "structure-graph.png", "PNG (*.png)")
-        if not path:
-            return
-        showing_d3 = (self.web is not None and self._stack.currentWidget() is self.web)
-        if showing_d3:
-            self._export_d3_png(path)
-        else:
-            self._export_widget_grab(path)
+        """Xuất khung đang xem ra PNG.
 
-    def _export_d3_png(self, path: str) -> None:
-        def on_result(data_url) -> None:
-            if not isinstance(data_url, str) or "," not in data_url:
-                self._export_widget_grab(path)
-                return
-            import base64
-            try:
-                with open(path, "wb") as f:
-                    f.write(base64.b64decode(data_url.split(",", 1)[1]))
-                self.status_message.emit(tr("structure.export_done", path=path))
-            except (OSError, ValueError) as exc:
-                self.status_message.emit(tr("structure.export_failed", err=str(exc)))
-        self.web.page().runJavaScript("window.exportPng ? window.exportPng() : ''", on_result)
-
-    def _export_widget_grab(self, path: str) -> None:
-        ok = self._stack.currentWidget().grab().save(path, "PNG")
-        if ok:
-            self.status_message.emit(tr("structure.export_done", path=path))
-        else:
-            self.status_message.emit(tr("structure.export_failed", err="grab() returned no image"))
+        Cách chụp tuỳ khung nào đang hiện — xem ``graph_export.py``.
+        """
+        graph_export.export_png(
+            parent=self,
+            showing=self._stack.currentWidget(),
+            web=self.web,
+            is_web_visible=self._stack.currentWidget() is self.web,
+            status=self.status_message.emit,
+        )
 
 
 __all__ = ["GraphRenderer"]
diff --git a/presentation/graph/graph_scene_builder.py b/presentation/graph/graph_scene_builder.py
new file mode 100644
index 0000000..16f6a6c
--- /dev/null
+++ b/presentation/graph/graph_scene_builder.py
@@ -0,0 +1,95 @@
+"""Dựng các item Qt cho khung đồ thị 2D — tách khỏi ``graph_renderer.py``.
+
+Đây là phần "biến dữ liệu thành hình" của GraphRAG: nhận một đồ thị đã quét
+cùng bảng toạ độ, đổ ``_Node``/``_Edge`` vào ``QGraphicsScene`` rồi trả lại
+danh sách item và trọng tâm cho bên gọi.
+
+Tách ra vì nó không cần biết gì về widget: không đọc thuộc tính nào của
+``GraphRenderer``, không phát tín hiệu, không chạm cấu hình. Nhờ thế mà thử
+được bằng một ``QGraphicsScene`` trần, và ``graph_renderer.py`` bớt đi phần
+duy nhất trong nó có tính toán hình học thật sự.
+"""
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Tuple
+
+from PySide6.QtCore import QPointF
+from PySide6.QtGui import QColor
+from PySide6.QtWidgets import QGraphicsScene
+
+from cowork_local.presentation.graph.graph_scene_items import _Edge, _Node
+
+
+def node_degrees(graph) -> Dict[str, int]:
+    """Số cạnh chạm vào từng node.
+
+    Dùng để định cỡ node: node càng nhiều liên kết thì vẽ càng to, nên mắt
+    người nhìn vào là thấy ngay đâu là đầu mối của cả đồ thị.
+    """
+    degree = {n.id: 0 for n in graph.nodes}
+    for edge in graph.edges:
+        if edge.source in degree:
+            degree[edge.source] += 1
+        if edge.target in degree:
+            degree[edge.target] += 1
+    return degree
+
+
+def node_radius(degree: int) -> int:
+    """Bán kính vẽ của một node theo bậc của nó.
+
+    Lấy căn bậc hai chứ không lấy tuyến tính: bậc tăng gấp bốn thì bán kính
+    mới gấp đôi, nhờ vậy DIỆN TÍCH mới tỉ lệ với bậc — đó mới là thứ mắt
+    người thật sự so sánh. Chặn trên ở 28 để một node trung tâm không nuốt
+    mất phần còn lại của đồ thị.
+    """
+    return int(8 + min(20, 2.2 * math.sqrt(degree)))
+
+
+def build_scene(
+    scene: QGraphicsScene, graph, pos: Dict[str, Tuple[float, float]], bg: str
+) -> Tuple[List[_Node], List[_Edge], QPointF]:
+    """Xoá sạch ``scene`` rồi dựng lại toàn bộ node và cạnh của ``graph``.
+
+    ``pos`` là toạ độ đã tính sẵn ở luồng nền (``{node_id: (x, y)}``); node
+    không có trong đó rơi về gốc toạ độ thay vì bị bỏ, để không im lặng đánh
+    mất dữ liệu.
+
+    Cạnh chỉ được vẽ khi CẢ HAI đầu đều có item — đồ thị bị cắt bớt
+    (``truncated``) hay dữ liệu lệch có thể trỏ tới node không tồn tại, và
+    một ``_Edge`` treo lơ lửng sẽ làm hỏng cả phép tính khung nhìn.
+
+    Trả về ``(danh sách node, danh sách cạnh, trọng tâm)``. Trọng tâm là
+    trung bình cộng toạ độ các node, dùng làm tâm khi thu phóng.
+    """
+    scene.clear()
+    scene.setBackgroundBrush(QColor(bg))
+
+    degree = node_degrees(graph)
+    items: Dict[str, _Node] = {}
+    node_items: List[_Node] = []
+    sx = sy = 0.0
+    for node in graph.nodes:
+        item = _Node(node, node_radius(degree.get(node.id, 0)))
+        x, y = pos.get(node.id, (0, 0))
+        item.setPos(x, y)
+        scene.addItem(item)
+        items[node.id] = item
+        node_items.append(item)
+        sx += x
+        sy += y
+
+    edge_items: List[_Edge] = []
+    for edge in graph.edges:
+        a, b = items.get(edge.source), items.get(edge.target)
+        if a and b:
+            e = _Edge(a, b, getattr(edge, "type", ""))
+            scene.addItem(e)
+            edge_items.append(e)
+
+    n = max(1, len(node_items))
+    return node_items, edge_items, QPointF(sx / n, sy / n)
+
+
+__all__ = ["build_scene", "node_degrees", "node_radius"]
diff --git a/presentation/graph/graph_scene_items.py b/presentation/graph/graph_scene_items.py
index e02bf96..1ccd364 100644
--- a/presentation/graph/graph_scene_items.py
+++ b/presentation/graph/graph_scene_items.py
@@ -22,12 +22,25 @@ class _Bridge(QObject):
 
     @Slot(str)
     def openPath(self, path: str) -> None:  # noqa: N802 - JS-facing name
+        """Cầu nối JavaScript → Python: Shift+click một node trên khung D3 thì mở thư
+        mục hoặc link lưu trữ của nó.
+        """
         if path:
             open_location(path)
 
 
 class _Edge(QGraphicsLineItem):
+    """Một cạnh trên khung Qt 2D, kèm nhãn tên quan hệ ở điểm giữa.
+
+    Màu cạnh lấy theo LOẠI quan hệ (contains/defines/method…) để nhìn đồ thị
+    là biết mỗi liên kết nghĩa là gì; cạnh không có loại thì mượn màu nhạt của
+    node nguồn. Nằm ở z=-1, tức dưới mọi node.
+    """
     def __init__(self, a: "_Node", b: "_Node", type_: str = ""):
+        """Một cạnh trên khung đồ thị, tô màu theo LOẠI quan hệ (chứa/định nghĩa/phương
+        thức…) để nhìn là biết liên kết ấy nghĩa gì; cạnh không có loại thì lấy màu
+        của node nguồn.
+        """
         super().__init__()
         self.a, self.b = a, b
         self.type = type_
@@ -54,6 +67,7 @@ class _Edge(QGraphicsLineItem):
         self.adjust()
 
     def adjust(self) -> None:
+        """Vẽ lại đường thẳng theo vị trí hai node và đặt nhãn vào đúng điểm giữa."""
         pa, pb = self.a.scenePos(), self.b.scenePos()
         self.setLine(pa.x(), pa.y(), pb.x(), pb.y())
         if self._label is not None:
@@ -63,7 +77,18 @@ class _Edge(QGraphicsLineItem):
 
 
 class _Node(QGraphicsEllipseItem):
+    """Một node hình tròn; bán kính do chỗ gọi tính theo bậc của node.
+
+    ``NODE_KIND_COLORS`` là mã màu theo LOẠI dữ liệu (mỗi loại một sắc), cố ý
+    giữ nguyên ở cả theme sáng lẫn tối để một loại luôn là một màu. Chỉ phần
+    khung viền/chữ mới đi theo theme.
+    """
     def __init__(self, data, radius: int):
+        """Một node hình tròn, bán kính theo số liên kết.
+
+        Màu theo loại node là mã hoá dữ liệu chứ không phải trang trí, nên cố định
+        qua mọi giao diện — cùng một loại luôn cùng một màu.
+        """
         super().__init__(-radius, -radius, 2 * radius, 2 * radius)
         self.data = data
         self.edges = []
@@ -85,6 +110,7 @@ class _Node(QGraphicsEllipseItem):
         label.setPos(radius + 3, -8)
 
     def itemChange(self, change, value):  # noqa: N802
+        """Kéo node thì kéo theo mọi cạnh dính vào nó."""
         if change == QGraphicsEllipseItem.ItemPositionHasChanged:
             for edge in self.edges:
                 edge.adjust()
@@ -92,17 +118,23 @@ class _Node(QGraphicsEllipseItem):
 
 
 class _GraphView(QGraphicsView):
+    """Khung xem đồ thị Qt 2D: lăn chuột để phóng, kéo nền để dời khung."""
     def __init__(self, scene):
+        """Khung xem đồ thị: kéo bằng chuột giữa để di chuyển, không kéo chọn vùng."""
         super().__init__(scene)
         self.setDragMode(QGraphicsView.NoDrag)
         self._panning = False
         self._pan_start = QPointF()
 
     def wheelEvent(self, e):  # noqa: N802
+        """Lăn chuột phóng to/thu nhỏ một nấc 1,15 lần."""
         self.scale(1.15 if e.angleDelta().y() > 0 else 1 / 1.15,
                    1.15 if e.angleDelta().y() > 0 else 1 / 1.15)
 
     def mousePressEvent(self, e):  # noqa: N802
+        """Nhấn trái vào chỗ TRỐNG thì bắt đầu kéo khung; nhấn trúng node thì để Qt
+        xử lý như chọn/kéo node bình thường.
+        """
         if e.button() == Qt.LeftButton and self.itemAt(e.pos()) is None:
             self._panning = True
             self._pan_start = e.position()
@@ -112,6 +144,7 @@ class _GraphView(QGraphicsView):
         super().mousePressEvent(e)
 
     def mouseMoveEvent(self, e):  # noqa: N802
+        """Đang kéo khung: dời hai thanh cuộn ngược chiều con trỏ."""
         if self._panning:
             delta = e.position() - self._pan_start
             self._pan_start = e.position()
@@ -122,6 +155,7 @@ class _GraphView(QGraphicsView):
         super().mouseMoveEvent(e)
 
     def mouseReleaseEvent(self, e):  # noqa: N802
+        """Thả chuột: kết thúc kéo khung, trả con trỏ về bình thường."""
         if self._panning:
             self._panning = False
             self.setCursor(Qt.ArrowCursor)
diff --git a/presentation/graph/structure_graph_view.py b/presentation/graph/structure_graph_view.py
index fc9e8af..b92f83a 100644
--- a/presentation/graph/structure_graph_view.py
+++ b/presentation/graph/structure_graph_view.py
@@ -21,9 +21,18 @@ _COLLAPSED_SIZES_HINT = (840, 320)   # matches the original single-class default
 
 
 class StructureGraphView(QWidget):
+    """Màn GraphRAG: ghép khung đồ thị (:class:`GraphRenderer`) và khung hỏi-đáp
+    (:class:`GraphQaWidget`) vào một splitter.
+
+    Vỏ này chỉ lắp ráp và chuyển tiếp bốn phương thức mà ``app.py`` và
+    ``ui/workspace_tab.py`` gọi tới; toàn bộ phần việc thật nằm ở hai widget con.
+    """
     status_message = Signal(str)
 
     def __init__(self, ctx: AppContext):
+        """Ghép hai nửa của màn GraphRAG: bên trái là đồ thị, bên phải là panel Hỏi
+        đáp.
+        """
         super().__init__()
         self.ctx = ctx
 
@@ -44,10 +53,14 @@ class StructureGraphView(QWidget):
         on_language_changed(self._retranslate)
 
     def _retranslate(self) -> None:
+        """Chuyển lệnh dịch lại xuống cho cả hai widget con."""
         self.renderer._retranslate()
         self.qa.retranslate()
 
     def _on_qa_collapse_changed(self, collapsed: bool) -> None:
+        """Gập/mở khung hỏi-đáp: gập thì thu về đúng bề rộng dải nắm, mở thì trả
+        splitter về tỉ lệ mặc định.
+        """
         strip_w = CollapseStrip.WIDTH + 2
         if collapsed:
             self.qa.setMaximumWidth(strip_w)
@@ -60,19 +73,24 @@ class StructureGraphView(QWidget):
 
     # ---- public API (app.py / ui/workspace_tab.py) --------------------------- #
     def schedule_rescan(self, path: str = "") -> None:
+        """Hẹn quét lại đồ thị sau khi thư mục có thay đổi."""
         self.renderer.schedule_rescan(path)
 
     def auto_scan_and_fit(self) -> None:
+        """Vào màn GraphRAG: hiện đồ thị, chỉ quét lại khi thật sự cần."""
         self.renderer.auto_scan_and_fit()
 
     def set_project(self, project_id: str) -> None:
+        """Khoá phạm vi quét vào một project (chuỗi rỗng là bỏ khoá)."""
         self.renderer.set_project(project_id)
 
     def prewarm(self) -> None:
+        """Dựng sẵn khung đồ thị trước khi người dùng bấm vào, để lần mở đầu không giật."""
         self.renderer.prewarm()
 
     def hideEvent(self, e):  # noqa: N802
         # Leaving the GraphRAG tab → drop the temporary extracted info.
+        """Rời màn GraphRAG thì xoá phần trích xuất tạm của khung hỏi-đáp."""
         self.qa.clear_extracts()
         super().hideEvent(e)
 
diff --git a/presentation/monitoring/monitoring_tab.py b/presentation/monitoring/monitoring_tab.py
index fc20357..59e8b4d 100644
--- a/presentation/monitoring/monitoring_tab.py
+++ b/presentation/monitoring/monitoring_tab.py
@@ -33,6 +33,12 @@ _UNBOUNDED_PAGE_SIZE = 100_000
 
 
 class MonitoringTab(QWidget):
+    """Vỏ màn Giám sát: dải 8 tab và phần dữ liệu dùng chung cho chúng.
+
+    Nhật ký kiểm toán được đọc MỘT lần mỗi nhịp làm mới rồi chia cho các tab,
+    nên quyết định "đọc từ nguồn cục bộ hay nguồn chia sẻ" chỉ xảy ra đúng một
+    lần chứ không phải ở từng tab.
+    """
     status_message = Signal(str)
 
     # ---- cầu tương thích sau khi tách 8 tab (R08-T08) --------------------
@@ -66,6 +72,14 @@ class MonitoringTab(QWidget):
     }
 
     def __getattr__(self, name):
+        """Cầu tương thích cho 55 control cũ mang tiền tố ``ov_``.
+
+        R08-T08 chuyển chúng về đúng tab/thẻ của mình và bỏ tiền tố, nhưng các
+        checker trong ``tools/`` vẫn hỏi theo tên cũ. Định tuyến theo TIỀN TỐ chứ
+        không dò mờ: ``overview_tab`` và ``permissions_card`` có tên trùng nhau
+        (``network_lbl`` ở cả hai — một cái là mức dùng mạng, một cái là quyền truy
+        cập mạng), dò mờ sẽ vớ nhầm cái tìm thấy trước.
+        """
         lay_khac = self._KHAC.get(name)
         if lay_khac is not None:
             return lay_khac(self)
@@ -84,6 +98,11 @@ class MonitoringTab(QWidget):
         raise AttributeError(name)
 
     def __init__(self, ctx: AppContext, cowork=None, structure=None, task_scheduler=None):
+        """Ghép các tab con của màn Giám sát.
+
+        Các widget được truyền vào đều có thể là None (test dựng tab lẻ) — mọi chỗ
+        dùng phải kiểm trước.
+        """
         super().__init__()
         self.ctx = ctx
         self._cowork = cowork
@@ -174,6 +193,7 @@ class MonitoringTab(QWidget):
         return out
 
     def select_subtab(self, index: int) -> None:
+        """Chuyển sang tab con thứ ``index`` (thanh menu bên trái gọi vào đây)."""
         if 0 <= index < self.tabs.count():
             self.tabs.setCurrentIndex(index)
 
@@ -182,18 +202,24 @@ class MonitoringTab(QWidget):
         self.tabs.tabBar().hide()
 
     def _show_action_logs_tab(self) -> None:
+        """Nhảy tới tab Nhật ký hành động (dùng khi bấm vào phần trích ở Tổng quan)."""
         self.tabs.setCurrentIndex(self.tabs.indexOf(self.action_tab))
 
     def _tab_visible(self, key: str) -> bool:
+        """Tab này có được hiện không: admin thấy hết, còn lại theo cấu hình
+        ``monitoring_visibility``.
+        """
         return self.ctx.role == "admin" or bool(self.ctx.config.monitoring_visibility.get(key, True))
 
     def _set_tab_text_if_present(self, widget, text: str) -> None:
+        """Đổi nhãn một tab, bỏ qua nếu tab đó đang bị ẩn theo phân quyền."""
         idx = self.tabs.indexOf(widget)
         if idx >= 0:
             self.tabs.setTabText(idx, text)
 
     # ---- i18n ---------------------------------------------------------------
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề và nhãn từng tab."""
         self._title.setText(tr("monitoring.title"))
         if self.tabs.count():
             self.tabs.setTabText(0, tr("monitoring.tab_overview"))
@@ -229,6 +255,11 @@ class MonitoringTab(QWidget):
         self.overview_tab.refresh(self._load_events())
 
     def _load_events(self) -> List[dict]:
+        """Đọc nhật ký kiểm toán, ưu tiên nguồn chia sẻ rồi mới tới nguồn cục bộ.
+
+        Có cấu hình thư mục chia sẻ VÀ đọc ra được dữ liệu thì dùng nó, để cả đội
+        nhìn chung một bức tranh; rỗng thì rơi về nhật ký của máy này.
+        """
         shared_dir = self.ctx.config.shared_dir
         if shared_dir:
             from ...core import telemetry_shared
@@ -252,6 +283,7 @@ class MonitoringTab(QWidget):
         service = MonitoringQueryService(repository)
 
         def _events_for(kind) -> List[dict]:
+            """Lấy toàn bộ sự kiện của một loại, không phân trang."""
             page = service.query(kind=kind, page_size=_UNBOUNDED_PAGE_SIZE)
             return [e.to_dict() for e in page.items]
 
diff --git a/presentation/monitoring/shared/__init__.py b/presentation/monitoring/shared/__init__.py
index e69de29..357b646 100644
--- a/presentation/monitoring/shared/__init__.py
+++ b/presentation/monitoring/shared/__init__.py
@@ -0,0 +1,3 @@
+"""Mảnh dùng chung của các tab Giám sát: bảng sự kiện, panel chi tiết, huy hiệu,
+bộ lọc và các hàm định dạng.
+"""
diff --git a/presentation/monitoring/shared/agent_kind_visuals.py b/presentation/monitoring/shared/agent_kind_visuals.py
new file mode 100644
index 0000000..f5064c2
--- /dev/null
+++ b/presentation/monitoring/shared/agent_kind_visuals.py
@@ -0,0 +1,67 @@
+"""Màu, huy hiệu và avatar của agent quản trị theo LOẠI VIỆC nó làm.
+
+Bảng Agents Admin xếp agent theo ``task_kind`` (search / monitor / cowork /
+graphrag / schedule / security / help). Ở đây gom toàn bộ phần "loại việc ấy
+trông thế nào": màu định danh cho avatar, tông huy hiệu cho ô Vai trò, tông
+huy hiệu cho ô Trạng thái.
+
+Khác với ``formatters.py::agent_avatar_colour`` — chỗ đó đoán màu bằng cách
+dò từ khoá trong TÊN agent, dùng cho các bảng chỉ có tên. Bảng quản trị biết
+chính xác loại việc nên tra thẳng, không phải đoán.
+
+Bảy loại, bảy tông riêng: không hai loại nào trùng màu huy hiệu, để phân biệt
+được bằng màu chứ không phải chỉ bằng chữ. Màu cố định, không đổi theo giao
+diện sáng/tối — cùng quy ước với avatar từng agent ở ``monitoring_tab.py``.
+"""
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QColor, QFont, QIcon, QPainter, QPixmap
+
+from .formatters import agent_initials
+
+#: Màu vòng tròn avatar theo loại việc.
+KIND_COLOUR = {
+    "search": "#8A8886", "monitor": "#FFB900", "cowork": "#0078D4",
+    "graphrag": "#8764B8", "schedule": "#107C10", "security": "#D13438",
+    "help": "#E3008C",
+}
+
+#: Tên đối tượng huy hiệu (định nghĩa trong ``theme.py``) cho ô Vai trò.
+KIND_BADGE = {
+    "search": "badgeNeutral", "monitor": "badgeWarn", "cowork": "badge",
+    "graphrag": "badgePurple", "schedule": "badgeSuccess", "security": "badgeDanger",
+    "help": "badgePink",
+}
+
+#: Tông huy hiệu cho ô Trạng thái, theo kết quả lần kiểm tra gần nhất.
+STATUS_BADGE = {
+    "unchecked": "badgeNeutral", "checking": "badgeWarn",
+    "ok": "badgeSuccess", "bad": "badgeDanger",
+}
+
+
+def kind_avatar_icon(kind: str, name: str, size: int = 20) -> QIcon:
+    """Avatar tròn cho một agent: nền là màu của loại việc, chữ là tên viết tắt.
+
+    Loại lạ (file cấu hình sửa tay, loại mới thêm mà quên khai màu) rơi về màu
+    xanh mặc định thay vì không vẽ gì — thiếu màu đúng vẫn hơn thiếu avatar.
+    """
+    pm = QPixmap(size, size)
+    pm.fill(Qt.transparent)
+    p = QPainter(pm)
+    p.setRenderHint(QPainter.Antialiasing)
+    p.setPen(Qt.NoPen)
+    p.setBrush(QColor(KIND_COLOUR.get(kind, "#0078D4")))
+    p.drawEllipse(0, 0, size, size)
+    font = QFont()
+    font.setPixelSize(max(7, size // 2))
+    font.setBold(True)
+    p.setFont(font)
+    p.setPen(QColor("#FFFFFF"))
+    p.drawText(pm.rect(), Qt.AlignCenter, agent_initials(name))
+    p.end()
+    return QIcon(pm)
+
+
+__all__ = ["KIND_COLOUR", "KIND_BADGE", "STATUS_BADGE", "kind_avatar_icon"]
diff --git a/presentation/monitoring/shared/ai_filter.py b/presentation/monitoring/shared/ai_filter.py
index b073b7e..c5339ca 100644
--- a/presentation/monitoring/shared/ai_filter.py
+++ b/presentation/monitoring/shared/ai_filter.py
@@ -13,12 +13,17 @@ from PySide6.QtWidgets import QLineEdit, QPushButton
 
 
 def start_ai_filter(ctx, search: QLineEdit, ai_btn: QPushButton, state: dict) -> None:
+    """Nhờ AI dịch câu tìm kiếm tự nhiên thành từ khoá lọc bảng sự kiện.
+
+    Ô tìm rỗng hoặc đang chạy dở thì bỏ qua.
+    """
     query = search.text().strip()
     if not query or state.get("worker") is not None:
         return
     ai_btn.setEnabled(False)
 
     def job(worker):
+        """Chạy nền: hỏi model từ khoá lọc tương ứng câu người dùng gõ."""
         provider = ctx.build_active_provider()
         reply = provider.chat([
             {"role": "system", "content":
@@ -29,11 +34,15 @@ def start_ai_filter(ctx, search: QLineEdit, ai_btn: QPushButton, state: dict) ->
         return {"keyword": (reply.get("content") or "").strip().splitlines()[0][:60]}
 
     def done(result: dict) -> None:
+        """Đổ từ khoá model trả về vào ô tìm và áp bộ lọc."""
         state["worker"] = None
         ai_btn.setEnabled(True)
         search.setText(result.get("keyword") or query)
 
     def failed(_err: str) -> None:
+        """Lọc bằng AI lỗi: chỉ mở khoá lại nút, giữ nguyên bộ lọc đang có — đây là
+        tiện ích phụ, hỏng thì không được làm phiền người dùng.
+        """
         state["worker"] = None
         ai_btn.setEnabled(True)
 
diff --git a/presentation/monitoring/shared/badges.py b/presentation/monitoring/shared/badges.py
index 1e7d037..81f668a 100644
--- a/presentation/monitoring/shared/badges.py
+++ b/presentation/monitoring/shared/badges.py
@@ -29,6 +29,7 @@ _ACTION_LABEL_KEYS = {
 
 
 def action_label(name: str) -> str:
+    """Nhãn đã dịch của một loại hành động; không có trong bảng thì trả nguyên tên."""
     key = _ACTION_LABEL_KEYS.get(name)
     return tr(key) if key else name
 
@@ -44,6 +45,7 @@ _STATUS_DEFAULT = ("badgePurple", "monitoring.status_blocked")
 
 
 def status_info(name: str, kind: str = "security_block", ok: bool = False) -> Tuple[str, str]:
+    """Cặp (tên style, khoá dịch) cho huy hiệu trạng thái của một sự kiện."""
     if name in _STATUS_INFO:
         return _STATUS_INFO[name]
     if kind == "security_block":
@@ -58,6 +60,11 @@ def status_info(name: str, kind: str = "security_block", ok: bool = False) -> Tu
 def severity_info(name: str, kind: str = "security_block", ok: bool = False) -> Tuple[str, str]:
     # An unapproved shell command is the one CRITICAL case; everything else
     # blocked is MEDIUM.
+    """Cặp (tên style, khoá dịch) cho huy hiệu mức nghiêm trọng.
+
+    Lệnh shell chạy mà chưa được duyệt là trường hợp NGHIÊM TRỌNG duy nhất; mọi
+    thứ bị chặn khác đều ở mức trung bình.
+    """
     if name in ("dangerous_command", "run_command"):
         return "badgeDanger", "monitoring.severity_critical"
     if kind == "security_block":
@@ -85,6 +92,10 @@ def agent_badge_name(name: str) -> str:
 
 
 def apply_badge(label: QLabel, object_name: str) -> None:
+    """Gán style cho một nhãn huy hiệu và ép Qt vẽ lại.
+
+    Phải ``unpolish``/``polish`` vì Qt không tự áp lại QSS khi ``objectName`` đổi.
+    """
     label.setObjectName(object_name)
     label.style().unpolish(label)
     label.style().polish(label)
diff --git a/presentation/monitoring/shared/event_detail_panel.py b/presentation/monitoring/shared/event_detail_panel.py
index 0d4885e..b25cb6e 100644
--- a/presentation/monitoring/shared/event_detail_panel.py
+++ b/presentation/monitoring/shared/event_detail_panel.py
@@ -33,6 +33,7 @@ class EventDetailPanel(QWidget):
     closed = Signal()
 
     def __init__(self):
+        """Panel chi tiết hiện đầy đủ một sự kiện đang chọn trong bảng."""
         super().__init__()
         self.setObjectName("monSection")
         self._detail_text = ""
@@ -64,12 +65,14 @@ class EventDetailPanel(QWidget):
         self._rows: Dict[str, Tuple[QLabel, QLabel]] = {}
 
         def _section(key: str) -> None:
+            """Thêm một dòng tiêu đề mục vào panel."""
             lbl = QLabel()
             lbl.setObjectName("detailSectionHdr")
             self._body_lay.addWidget(lbl)
             self._section_hdrs.append((key, lbl))
 
         def _field(key: str) -> QLabel:
+            """Thêm một hàng nhãn–giá trị và ghi nhớ để cập nhật sau."""
             lbl, val = kv_row(self._body_lay)
             self._rows[key] = (lbl, val)
             return val
@@ -121,6 +124,7 @@ class EventDetailPanel(QWidget):
         outer.addLayout(footer)
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._title_lbl.setText(tr("monitoring.security_detail_title"))
         self._close_btn.setToolTip(tr("monitoring.security_detail_close"))
         self._footer_close_btn.setText(tr("monitoring.security_detail_close"))
@@ -146,6 +150,7 @@ class EventDetailPanel(QWidget):
             self._reset_copy_btn()
 
     def show_event(self, ev: dict, row: int) -> None:
+        """Hiện chi tiết một sự kiện; trường trống hiển thị dấu "—" thay vì để rỗng."""
         na = "—"
         self._rows["time"][1].setText(fmt_event_time_full(ev.get("ts", "")) or na)
 
@@ -179,11 +184,13 @@ class EventDetailPanel(QWidget):
         apply_badge(self._severity_val, severity_badge)
 
     def _copy_detail(self) -> None:
+        """Chép toàn bộ chi tiết vào clipboard và đổi nhãn nút để báo đã chép."""
         QGuiApplication.clipboard().setText(self._detail_text)
         self._copy_btn.setText(tr("monitoring.detail_copied"))
         self._copy_btn.setIcon(icon("check"))
         QTimer.singleShot(1500, self._reset_copy_btn)
 
     def _reset_copy_btn(self) -> None:
+        """Trả nút Sao chép về nhãn ban đầu sau vài giây."""
         self._copy_btn.setText(tr("monitoring.detail_copy"))
         self._copy_btn.setIcon(icon("document"))
diff --git a/presentation/monitoring/shared/event_table.py b/presentation/monitoring/shared/event_table.py
index b487e2b..9a66299 100644
--- a/presentation/monitoring/shared/event_table.py
+++ b/presentation/monitoring/shared/event_table.py
@@ -26,10 +26,18 @@ class _TimeItem(QTableWidgetItem):
     ISO ``ts`` each item is built from instead of its displayed text."""
 
     def __init__(self, raw_ts: str, display: str):
+        """Ô thời gian giữ luôn chuỗi gốc: hiện ra là chữ đã rút gọn, nhưng sắp xếp
+        phải theo mốc thật chứ không theo thứ tự chữ cái.
+        """
         super().__init__(display)
         self._raw_ts = raw_ts
 
     def __lt__(self, other):
+        """So sánh theo mốc thời gian gốc, không theo chuỗi hiển thị.
+
+        Sắp theo chuỗi đã định dạng sẽ ra thứ tự sai ngay khi định dạng có chữ
+        ("5 phút trước" đứng trước "hôm qua").
+        """
         if isinstance(other, _TimeItem):
             return self._raw_ts < other._raw_ts
         return super().__lt__(other)
@@ -56,6 +64,11 @@ class EventTable(QTableWidget):
 
     def __init__(self, show_result: bool = True):
         # Security Events drops the result column entirely (see _ACTION_TINTS).
+        """Bảng sự kiện dùng chung của các tab Giám sát.
+
+        ``show_result`` tắt cột Kết quả cho màn Sự kiện bảo mật — ở đó mọi dòng đều
+        là thất bại nên cột ấy chỉ tốn chỗ.
+        """
         self._show_result = show_result
         super().__init__(0, 7 if show_result else 6)
         self.setEditTriggers(QTableWidget.NoEditTriggers)
@@ -74,6 +87,7 @@ class EventTable(QTableWidget):
             header.setSectionResizeMode(col, QHeaderView.ResizeToContents)
 
     def retranslate(self) -> None:
+        """Áp lại tên cột theo ngôn ngữ đang chọn."""
         cols = [tr("monitoring.col_time"),
                 tr("monitoring.col_agent") if not self._show_result else tr("monitoring.col_role"),
                 tr("monitoring.col_account"), tr("monitoring.col_machine")]
@@ -85,6 +99,11 @@ class EventTable(QTableWidget):
         self.setHorizontalHeaderLabels(cols)
 
     def set_events(self, events: List[dict]) -> None:
+        """Đổ danh sách sự kiện vào bảng: mới nhất lên đầu, cắt ở ``_MAX_ROWS``.
+
+        Tắt sắp xếp trong lúc đổ dữ liệu — để bật, Qt sắp lại sau mỗi dòng và việc
+        nạp chậm đi theo bậc hai.
+        """
         events = sorted(events, key=lambda e: e.get("ts", ""), reverse=True)[:_MAX_ROWS]
         self.setSortingEnabled(False)
         self.setRowCount(len(events))
@@ -132,6 +151,7 @@ class EventTable(QTableWidget):
         self.apply_filter(getattr(self, "_filter_needle", ""))
 
     def apply_filter(self, needle: str) -> None:
+        """Ẩn/hiện dòng theo từ khoá tìm kiếm (không phân biệt hoa thường)."""
         self._filter_needle = (needle or "").strip().lower()
         for row in range(self.rowCount()):
             if not self._filter_needle:
@@ -144,6 +164,7 @@ class EventTable(QTableWidget):
             self.setRowHidden(row, not match)
 
     def event_at_row(self, row: int) -> Optional[dict]:
+        """Bản ghi sự kiện gắn với một dòng; ``None`` nếu dòng trống."""
         item = self.item(row, 0)
         return item.data(Qt.UserRole) if item else None
 
@@ -156,12 +177,14 @@ class ClickOutsideCloser(QObject):
     splitter's handle)."""
 
     def __init__(self, table: "EventTable", panel: QWidget, container: QWidget):
+        """Bấm ra ngoài panel chi tiết thì đóng nó lại."""
         super().__init__(container)
         self._table = table
         self._panel = panel
         self._container = container
 
     def eventFilter(self, obj, event) -> bool:
+        """Bắt cú bấm chuột trong toàn khung: rơi ngoài cả bảng lẫn panel thì đóng panel."""
         if event.type() == QEvent.MouseButtonPress and self._panel.isVisible():
             global_pos = event.globalPosition().toPoint()
             top_left = self._container.mapToGlobal(self._container.rect().topLeft())
diff --git a/presentation/monitoring/shared/filter_scaffold.py b/presentation/monitoring/shared/filter_scaffold.py
index 47b8e75..8c02e06 100644
--- a/presentation/monitoring/shared/filter_scaffold.py
+++ b/presentation/monitoring/shared/filter_scaffold.py
@@ -30,6 +30,12 @@ def _sync_event_detail(table: EventTable, panel: EventDetailPanel) -> None:
     # currentRow() alone is not enough: clearSelection() (used by the panel's
     # close button) drops the selection but leaves the current cell in
     # place, so a stale currentRow() would keep the panel open.
+    """Đồng bộ panel chi tiết với dòng đang chọn trong bảng.
+
+    Chỉ nhìn ``currentRow()`` là chưa đủ: ``clearSelection()`` (nút đóng của panel
+    dùng) bỏ vùng chọn nhưng GIỮ nguyên ô hiện tại, nên chỉ dựa vào
+    ``currentRow()`` thì panel sẽ không bao giờ đóng.
+    """
     row = table.currentRow()
     has_selection = bool(table.selectedItems())
     ev = table.event_at_row(row) if (has_selection and row >= 0) else None
@@ -44,6 +50,12 @@ def build_filter_scaffold(
     with_detail: bool = False,
     on_ai_filter: Optional[Callable[[QLineEdit, QPushButton], None]] = None,
 ) -> Dict[str, object]:
+    """Dựng khung chung cho một tab sự kiện: tiêu đề, nút làm mới, ô tìm kiếm,
+    nút lọc bằng AI và panel chi tiết.
+
+    Bốn tab sự kiện của màn Giám sát chỉ khác nhau ở nguồn dữ liệu, nên phần vỏ
+    này được dựng một lần và dùng chung.
+    """
     lay = QVBoxLayout(page)
     lay.setContentsMargins(0, 0, 0, 0)
     parts: Dict[str, object] = {}
diff --git a/presentation/monitoring/shared/formatters.py b/presentation/monitoring/shared/formatters.py
index 00760cb..4d41df7 100644
--- a/presentation/monitoring/shared/formatters.py
+++ b/presentation/monitoring/shared/formatters.py
@@ -18,6 +18,7 @@ from ....i18n import tr
 
 
 def _parse_iso(ts: str) -> Optional[datetime]:
+    """Đọc chuỗi thời gian ISO; sai định dạng thì trả ``None``."""
     try:
         return datetime.fromisoformat(ts)
     except (TypeError, ValueError):
@@ -25,6 +26,7 @@ def _parse_iso(ts: str) -> Optional[datetime]:
 
 
 def fmt_bytes(n: float) -> str:
+    """Đổi số byte sang chuỗi dễ đọc (B / KB / MB / GB)."""
     for unit in ("B", "KB", "MB", "GB"):
         if n < 1024:
             return f"{n:.0f} {unit}"
diff --git a/presentation/monitoring/shared/open_settings.py b/presentation/monitoring/shared/open_settings.py
index 4e9377a..ed27fe2 100644
--- a/presentation/monitoring/shared/open_settings.py
+++ b/presentation/monitoring/shared/open_settings.py
@@ -10,6 +10,11 @@ from PySide6.QtWidgets import QWidget
 
 
 def open_settings_and_notify(ctx, parent: QWidget, on_changed: Callable[[], None]) -> None:
+    """Mở hộp thoại Cài đặt rồi gọi ``on_changed`` sau khi đóng.
+
+    Các thẻ trong màn Giám sát dùng chung hàm này để làm mới sau khi người dùng
+    sửa cấu hình an toàn.
+    """
     from ....ui.settings_dialog import SettingsDialog
 
     dlg = SettingsDialog(ctx, parent)
diff --git a/presentation/monitoring/tabs/__init__.py b/presentation/monitoring/tabs/__init__.py
index e69de29..ceade39 100644
--- a/presentation/monitoring/tabs/__init__.py
+++ b/presentation/monitoring/tabs/__init__.py
@@ -0,0 +1,3 @@
+"""Tám tab của màn Giám sát, mỗi tab một file: Tổng quan, Sandbox, Sự kiện bảo
+mật, Lịch sử MCP, Nhật ký hành động, Trạng thái Agent, Quản trị Agent, Công cụ.
+"""
diff --git a/presentation/monitoring/tabs/action_logs_tab.py b/presentation/monitoring/tabs/action_logs_tab.py
index ff9f1d6..60c2b27 100644
--- a/presentation/monitoring/tabs/action_logs_tab.py
+++ b/presentation/monitoring/tabs/action_logs_tab.py
@@ -15,7 +15,9 @@ from ..shared.filter_scaffold import build_filter_scaffold
 
 
 class ActionLogsTab(QWidget):
+    """Tab "Nhật ký hành động": bảng mọi thao tác đọc/ghi tệp và chạy lệnh của agent."""
     def __init__(self, ctx, on_refresh_all: Callable[[], None]):
+        """Tab Nhật ký hành động: bảng sự kiện kèm bộ lọc dùng chung."""
         super().__init__()
         self._ctx = ctx
         self._ai_state: dict = {}
@@ -32,9 +34,11 @@ class ActionLogsTab(QWidget):
         self.detail_panel = parts["detail_panel"]
 
     def set_events(self, events: List[dict]) -> None:
+        """Đổ danh sách sự kiện vào bảng."""
         self.table.set_events(events)
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.table.retranslate()
         self.filter_edit.setPlaceholderText(tr("monitoring.filter_placeholder"))
         self.detail_panel.retranslate()
@@ -42,4 +46,5 @@ class ActionLogsTab(QWidget):
         self.title_refresh_btn.setText(tr("monitoring.refresh"))
 
     def _start_ai_filter(self, search: QLineEdit, ai_btn: QPushButton) -> None:
+        """Nhờ AI dịch câu tìm kiếm tự nhiên thành từ khoá lọc."""
         start_ai_filter(self._ctx, search, ai_btn, self._ai_state)
diff --git a/presentation/monitoring/tabs/agent_edit_dialog.py b/presentation/monitoring/tabs/agent_edit_dialog.py
index 7b3e9e5..e93c935 100644
--- a/presentation/monitoring/tabs/agent_edit_dialog.py
+++ b/presentation/monitoring/tabs/agent_edit_dialog.py
@@ -35,6 +35,11 @@ class AgentEditDialog(QDialog):
     def __init__(self, parent=None, ctx: Optional[AppContext] = None,
                  agent: Optional[admin_agents.AdminAgent] = None,
                  default_model_hint: str = ""):
+        """Form thêm/sửa một agent quản trị.
+
+        Danh sách model của từng provider được nạp nền và nhớ lại, để đổi qua đổi
+        lại giữa các provider không phải gọi mạng lần nữa.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._existing = agent
@@ -96,15 +101,18 @@ class AgentEditDialog(QDialog):
         form.addRow(buttons)
 
     def _load_live_models(self) -> None:
+        """Nạp danh sách model đang sống của mọi provider, ở luồng nền."""
         if self.ctx is None:
             return
         self.load_models_btn.setEnabled(False)
         ctx = self.ctx
 
         def job(_worker: AgentWorker):
+            """Chạy nền: hỏi từng provider danh sách model."""
             return preview_ai.fetch_live_models(ctx)
 
         def done(result: dict) -> None:
+            """Ghi nhớ danh sách model rồi nạp vào ô chọn theo provider đang chọn."""
             self.load_models_btn.setEnabled(True)
             self._live_models = result or {}
             self._refresh_model_combo()
@@ -113,6 +121,7 @@ class AgentEditDialog(QDialog):
                                         tr("agents_admin.load_models_empty"))
 
         def failed(err: str) -> None:
+            """Nạp model lỗi: hiện cảnh báo và mở khoá lại nút."""
             self.load_models_btn.setEnabled(True)
             QMessageBox.warning(self, tr("agents_admin.add_title"), err)
 
@@ -123,6 +132,7 @@ class AgentEditDialog(QDialog):
         w.start()
 
     def _refresh_model_combo(self) -> None:
+        """Nạp lại ô chọn model theo provider đang chọn, giữ nguyên thứ đang gõ."""
         provider_key = self.provider_combo.currentData()
         current_text = self.model_combo.currentText().strip()
         models = self._live_models.get(provider_key, []) if provider_key else []
@@ -133,6 +143,7 @@ class AgentEditDialog(QDialog):
         self.model_combo.blockSignals(False)
 
     def result_fields(self) -> Dict[str, str]:
+        """Các trường agent lấy từ form, để chỗ gọi dựng bản ghi."""
         return {
             "name": self.name_edit.text().strip(),
             "task_kind": self.kind_combo.currentData(),
diff --git a/presentation/monitoring/tabs/agent_status_tab.py b/presentation/monitoring/tabs/agent_status_tab.py
index 6877114..6915c1c 100644
--- a/presentation/monitoring/tabs/agent_status_tab.py
+++ b/presentation/monitoring/tabs/agent_status_tab.py
@@ -18,8 +18,10 @@ from ..shared.formatters import agent_avatar_icon
 
 
 class AgentStatusTab(QWidget):
+    """Tab "Trạng thái Agent": đang có bao nhiêu lượt chat, task và luồng chạy."""
     def __init__(self, ctx, on_refresh_all: Callable[[], None],
                 cowork=None, structure=None, task_scheduler=None):
+        """Tab Tình trạng agent. Các widget truyền vào có thể là None khi dựng tab lẻ."""
         super().__init__()
         self._ctx = ctx
         self._cowork = cowork
@@ -45,6 +47,7 @@ class AgentStatusTab(QWidget):
         self.title_refresh_btn = parts["title_refresh_btn"]
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.title_lbl.setText(tr(self.title_key))
         self.title_refresh_btn.setText(tr("monitoring.refresh"))
         self.table.setHorizontalHeaderLabels([
@@ -52,6 +55,7 @@ class AgentStatusTab(QWidget):
         ])
 
     def refresh(self) -> None:
+        """Đếm lại số việc đang chạy ở từng phân hệ và cập nhật bảng."""
         cowork_n = len(self._cowork.active_workers()) if self._cowork is not None else 0
         task_n = self._task_scheduler.running_count() if self._task_scheduler is not None else 0
         ask_worker = getattr(self._structure, "_ask_worker", None)
diff --git a/presentation/monitoring/tabs/agents_admin_tab.py b/presentation/monitoring/tabs/agents_admin_tab.py
index 711f8f5..865941f 100644
--- a/presentation/monitoring/tabs/agents_admin_tab.py
+++ b/presentation/monitoring/tabs/agents_admin_tab.py
@@ -12,88 +12,45 @@ The header's "Kiểm tra tất cả" icon probes each agent's effective provider
 (``check_agent``) and shows the result as the Trạng thái pill (OK / error /
 checking…) — separate from the per-row Kích hoạt switch, which only toggles
 the config flag.
+
+Màu, huy hiệu và avatar theo loại việc nằm ở
+``../shared/agent_kind_visuals.py``. File này từng giữ bản sao riêng của ba
+hàm dùng chung — ``_initials``, ``_fmt_updated``, ``_kind_avatar_icon`` —
+giống hệt ``shared/formatters.py`` đến từng dòng; nay dùng thẳng bản chung
+để định dạng thời gian và avatar không lệch nhau giữa các bảng Giám sát.
 """
 from __future__ import annotations
 
-from .agent_edit_dialog import AgentEditDialog
-
 from datetime import datetime
-from typing import Dict, List, Optional
+from typing import Dict, List
 
 from PySide6.QtCore import QSize, Qt
-from PySide6.QtGui import QColor, QFont, QIcon, QPainter, QPixmap
 from PySide6.QtWidgets import (
-    QCheckBox, QComboBox, QDialog, QDialogButtonBox, QFormLayout, QHBoxLayout,
-    QHeaderView, QLabel, QLineEdit, QMessageBox, QPlainTextEdit, QPushButton,
+    QHBoxLayout, QHeaderView, QLabel, QMessageBox, QPushButton,
     QTableWidget, QTableWidgetItem, QVBoxLayout, QWidget,
 )
 
 from ....config import PROVIDER_LABELS
-from ....core import admin_agents, preview_ai
+from ....core import admin_agents
 from ....core.worker import AgentWorker
 from ....i18n import on_language_changed, tr
 from ....state import AppContext
 from ....ui.icons import icon
 from ....ui.widgets import ToggleSwitch, badge_pill_widget
+from .agent_edit_dialog import AgentEditDialog
+from ..shared.agent_kind_visuals import KIND_BADGE, STATUS_BADGE, kind_avatar_icon
+from ..shared.formatters import fmt_event_time
 
 _PROVIDER_DEFAULT = ""   # "" = each machine's own active provider (unchanged default)
 
-# Identity colour (avatar circle) + badge tone per task_kind — same "fixed
-# colour regardless of theme" convention as monitoring_tab.py's per-agent
-# avatars, plus a badge object name (theme.py) for the Vai trò pill. Seven
-# kinds, seven distinct tones — no two kinds share a badge colour.
-_KIND_COLOUR = {
-    "search": "#8A8886", "monitor": "#FFB900", "cowork": "#0078D4",
-    "graphrag": "#8764B8", "schedule": "#107C10", "security": "#D13438",
-    "help": "#E3008C",
-}
-_KIND_BADGE = {
-    "search": "badgeNeutral", "monitor": "badgeWarn", "cowork": "badge",
-    "graphrag": "badgePurple", "schedule": "badgeSuccess", "security": "badgeDanger",
-    "help": "badgePink",
-}
-_STATUS_BADGE = {
-    "unchecked": "badgeNeutral", "checking": "badgeWarn",
-    "ok": "badgeSuccess", "bad": "badgeDanger",
-}
-
-
-def _initials(name: str) -> str:
-    return "".join(w[0] for w in name.split() if w)[:2].upper()
-
-
-def _fmt_updated(ts: str) -> str:
-    """"dd/MM hh:mm" — same Cập nhật/Thời gian format as Monitoring's
-    Bảo mật/MCP/Hành động tables (``_fmt_event_time`` in monitoring_tab.py)."""
-    try:
-        dt = datetime.fromisoformat(ts)
-    except (TypeError, ValueError):
-        return ts
-    return dt.strftime("%d/%m %H:%M")
-
-
-def _kind_avatar_icon(kind: str, name: str, size: int = 20) -> QIcon:
-    pm = QPixmap(size, size)
-    pm.fill(Qt.transparent)
-    p = QPainter(pm)
-    p.setRenderHint(QPainter.Antialiasing)
-    p.setPen(Qt.NoPen)
-    p.setBrush(QColor(_KIND_COLOUR.get(kind, "#0078D4")))
-    p.drawEllipse(0, 0, size, size)
-    font = QFont()
-    font.setPixelSize(max(7, size // 2))
-    font.setBold(True)
-    p.setFont(font)
-    p.setPen(QColor("#FFFFFF"))
-    p.drawText(pm.rect(), Qt.AlignCenter, _initials(name))
-    p.end()
-    return QIcon(pm)
-
-
-
-
 class AgentsAdminTab(QWidget):
+    """Tab "Quản trị Agent": cấu hình prompt, provider và model cho từng agent chuyên trách, kèm nút kiểm tra tình trạng hoạt động."""
     def __init__(self, ctx: AppContext):
+        """Dựng bảng agent quản trị.
+
+        Kết quả kiểm tra lần gần nhất được giữ trong ``_status`` và sống qua các lần
+        vẽ lại — người dùng bấm Kiểm tra một lần rồi lọc/sắp xếp vẫn thấy kết quả.
+        """
         super().__init__()
         self.ctx = ctx
         # Last operational-health result per agent_id → (ok, message). Populated
@@ -178,14 +135,17 @@ class AgentsAdminTab(QWidget):
 
     # ---- storage ---------------------------------------------------------
     def _dir(self):
+        """Thư mục chứa agent quản trị (dùng thư mục chia sẻ nếu có cấu hình)."""
         return admin_agents.agents_admin_dir(self.ctx.config.shared_dir)
 
     def _default_model_hint(self) -> str:
+        """Model mặc định gợi ý cho agent mới — lấy từ provider đang chọn."""
         conf = self.ctx.config.provider_conf(self.ctx.config.active_provider)
         return conf.get("model", "")
 
     # ---- CRUD -------------------------------------------------------------
     def _add(self) -> None:
+        """Thêm một agent quản trị mới qua hộp thoại."""
         dlg = AgentEditDialog(self, ctx=self.ctx, default_model_hint=self._default_model_hint())
         if not dlg.exec():
             return
@@ -201,6 +161,7 @@ class AgentsAdminTab(QWidget):
         self.refresh()
 
     def _edit_agent(self, agent_id: str) -> None:
+        """Sửa một agent; id không còn tồn tại thì bỏ qua."""
         agent = admin_agents.load_agent(agent_id, self._dir())
         if agent is None:
             return
@@ -224,6 +185,7 @@ class AgentsAdminTab(QWidget):
         self.refresh()
 
     def _delete_agent(self, agent_id: str) -> None:
+        """Xoá một agent sau khi hỏi xác nhận."""
         agent = admin_agents.load_agent(agent_id, self._dir())
         if agent is None:
             return
@@ -235,6 +197,7 @@ class AgentsAdminTab(QWidget):
         self.refresh()
 
     def _set_enabled(self, agent_id: str, enabled: bool) -> None:
+        """Bật/tắt một agent; trạng thái không đổi thì không ghi đĩa."""
         agent = admin_agents.load_agent(agent_id, self._dir())
         if agent is None or agent.enabled == enabled:
             return
@@ -248,7 +211,7 @@ class AgentsAdminTab(QWidget):
     # ---- view --------------------------------------------------------------
     def _status_cell(self, agent_id: str) -> tuple:
         """(state_key, display_text, tooltip) for the Trạng thái pill —
-        state_key indexes _STATUS_BADGE for the badge's colour tone."""
+        state_key indexes STATUS_BADGE for the badge's colour tone."""
         res = self._status.get(agent_id)
         if res is None:
             return ("unchecked", tr("agents_admin.status_unchecked").lstrip("— ").strip(),
@@ -259,6 +222,7 @@ class AgentsAdminTab(QWidget):
         return ("ok" if ok else "bad"), (tr("agents_admin.status_ok") if ok else tr("agents_admin.status_bad")), msg
 
     def _toggle_widget(self, agent_id: str, enabled: bool) -> QWidget:
+        """Dựng ô công tắc bật/tắt cho một dòng trong bảng."""
         container = QWidget()
         container.setStyleSheet("background: transparent;")
         lay = QHBoxLayout(container)
@@ -271,6 +235,7 @@ class AgentsAdminTab(QWidget):
         return container
 
     def _row_actions_widget(self, agent_id: str) -> QWidget:
+        """Dựng cụm nút sửa/xoá cho một dòng trong bảng."""
         container = QWidget()
         container.setStyleSheet("background: transparent;")
         lay = QHBoxLayout(container)
@@ -295,6 +260,7 @@ class AgentsAdminTab(QWidget):
     def refresh(self) -> None:
         # Make sure the built-in in-app Help assistant exists, so the Admin can
         # manage its provider/model here (the floating Help widget uses it).
+        """Vẽ lại bảng agent."""
         admin_agents.ensure_help_agent(self._dir())
         agents = admin_agents.list_agents(self._dir())
         self.table.setRowCount(len(agents))
@@ -307,10 +273,10 @@ class AgentsAdminTab(QWidget):
                 model = tr("agents_admin.default_model", model=default_model or "—")
 
             name_item = QTableWidgetItem(agent.name)
-            name_item.setIcon(_kind_avatar_icon(agent.task_kind, agent.name))
+            name_item.setIcon(kind_avatar_icon(agent.task_kind, agent.name))
             self.table.setItem(row, 0, name_item)
 
-            kind_tone = _KIND_BADGE.get(agent.task_kind, "badge")
+            kind_tone = KIND_BADGE.get(agent.task_kind, "badge")
             self.table.setCellWidget(
                 row, 1, badge_pill_widget(tr(f"agents_admin.kind.{agent.task_kind}"), kind_tone))
 
@@ -318,12 +284,12 @@ class AgentsAdminTab(QWidget):
             self.table.setCellWidget(row, 3, self._toggle_widget(agent.agent_id, agent.enabled))
 
             state_key, status_text, status_tip = self._status_cell(agent.agent_id)
-            status_widget = badge_pill_widget(status_text, _STATUS_BADGE[state_key])
+            status_widget = badge_pill_widget(status_text, STATUS_BADGE[state_key])
             if status_tip:
                 status_widget.setToolTip(status_tip)
             self.table.setCellWidget(row, 4, status_widget)
 
-            self.table.setItem(row, 5, QTableWidgetItem(_fmt_updated(agent.updated)))
+            self.table.setItem(row, 5, QTableWidgetItem(fmt_event_time(agent.updated)))
             self.table.setCellWidget(row, 6, self._row_actions_widget(agent.agent_id))
 
         # ResizeToContents doesn't measure a cell WIDGET's real width (only
@@ -349,14 +315,17 @@ class AgentsAdminTab(QWidget):
         ctx = self.ctx
 
         def job(_worker: AgentWorker) -> dict:
+            """Chạy nền: gọi thử từng agent để kiểm tra tình trạng hoạt động."""
             return {a.agent_id: admin_agents.check_agent(ctx, a) for a in agents}
 
         def done(result: dict) -> None:
+            """Ghi kết quả kiểm tra vào bảng trạng thái rồi vẽ lại."""
             self.check_btn.setEnabled(True)
             self._status.update(result or {})
             self.refresh()
 
         def failed(err: str) -> None:
+            """Kiểm tra lỗi: đánh dấu mọi agent là hỏng kèm lý do (cắt ở 200 ký tự)."""
             self.check_btn.setEnabled(True)
             for a in agents:
                 self._status[a.agent_id] = (False, err[:200])
@@ -369,6 +338,7 @@ class AgentsAdminTab(QWidget):
         w.start()
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, gợi ý và tên cột."""
         self._title_lbl.setText(tr("agents_admin.page_title"))
         self._hint.setText(tr("agents_admin.hint"))
         self.table.setHorizontalHeaderLabels([
diff --git a/presentation/monitoring/tabs/mcp_tab.py b/presentation/monitoring/tabs/mcp_tab.py
index 5667ace..b355ecb 100644
--- a/presentation/monitoring/tabs/mcp_tab.py
+++ b/presentation/monitoring/tabs/mcp_tab.py
@@ -15,7 +15,9 @@ from ..shared.filter_scaffold import build_filter_scaffold
 
 
 class McpTab(QWidget):
+    """Tab "Lịch sử MCP": bảng các lượt gọi tool MCP kèm độ trễ và kết quả."""
     def __init__(self, ctx, on_refresh_all: Callable[[], None]):
+        """Tab Lịch sử MCP: bảng sự kiện kèm bộ lọc dùng chung."""
         super().__init__()
         self._ctx = ctx
         self._ai_state: dict = {}
@@ -32,9 +34,11 @@ class McpTab(QWidget):
         self.detail_panel = parts["detail_panel"]
 
     def set_events(self, events: List[dict]) -> None:
+        """Đổ danh sách sự kiện vào bảng."""
         self.table.set_events(events)
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.table.retranslate()
         self.filter_edit.setPlaceholderText(tr("monitoring.filter_placeholder"))
         self.detail_panel.retranslate()
@@ -42,4 +46,5 @@ class McpTab(QWidget):
         self.title_refresh_btn.setText(tr("monitoring.refresh"))
 
     def _start_ai_filter(self, search: QLineEdit, ai_btn: QPushButton) -> None:
+        """Nhờ AI dịch câu tìm kiếm tự nhiên thành từ khoá lọc."""
         start_ai_filter(self._ctx, search, ai_btn, self._ai_state)
diff --git a/presentation/monitoring/tabs/overview_tab.py b/presentation/monitoring/tabs/overview_tab.py
index 7ad1ce4..dff23ac 100644
--- a/presentation/monitoring/tabs/overview_tab.py
+++ b/presentation/monitoring/tabs/overview_tab.py
@@ -25,10 +25,21 @@ from .sandbox_tab import SandboxDetailsCard
 
 
 class OverviewTab(QWidget):
+    """Tab "Tổng quan" của màn Giám sát: tài nguyên máy, thẻ token/chi phí, ngân
+    sách, trạng thái sandbox, hoạt động gần đây và trích nhật ký kiểm toán.
+
+    Một cột dọc duy nhất, mỗi phần là một mục có tiêu đề — bố cục này là chủ ý
+    để mắt quét từ trên xuống thay vì phải nhảy giữa hai cột.
+    """
     def __init__(self, ctx, *, on_status_message: Callable[[str], None],
                 on_settings_changed: Callable[[], None],
                 on_view_all_action_logs: Callable[[], None],
                 action_logs_tab_visible: bool):
+        """Tab Tổng quan.
+
+        Mọi việc ra ngoài tab (báo trạng thái, mở màn khác) đều đi qua callback
+        truyền vào, nên tab này không cần biết cửa sổ chính.
+        """
         super().__init__()
         self.ctx = ctx
         self._on_status_message = on_status_message
@@ -64,6 +75,7 @@ class OverviewTab(QWidget):
 
     # ---- Token Usage & Cost ------------------------------------------------
     def _build_usage_section(self, root: QVBoxLayout) -> None:
+        """Dựng mục thẻ token/chi phí kèm thẻ ngân sách."""
         self.usage_group = QGroupBox()
         self.usage_group.setObjectName("monSection")
         usage_lay = QGridLayout(self.usage_group)
@@ -88,6 +100,7 @@ class OverviewTab(QWidget):
 
     # ---- Recent Activity ----------------------------------------------------
     def _build_activity_section(self) -> None:
+        """Dựng mục "Hoạt động gần đây" (thêm vào cột ở dưới, cạnh nhật ký kiểm toán)."""
         self.activity_group = QGroupBox()
         self.activity_group.setObjectName("monSection")
         act_lay = QVBoxLayout(self.activity_group)
@@ -98,12 +111,16 @@ class OverviewTab(QWidget):
 
     # ---- Resource Usage -------------------------------------------------------
     def _build_resource_section(self, root: QVBoxLayout) -> None:
+        """Dựng mục tài nguyên: CPU, bộ nhớ, đĩa, mạng và trạng thái sandbox."""
         self.resource_group = QGroupBox()
         self.resource_group.setObjectName("monSection")
         res_lay = QHBoxLayout(self.resource_group)
         res_lay.setSpacing(6)
 
         def _pair():
+            """Thêm một cặp nhãn–giá trị vào hàng tài nguyên, tự chèn dấu phân cách giữa
+            các cặp.
+            """
             if not self._res_first:
                 sep = QLabel(chr(0xB7))
                 sep.setObjectName("hint")
@@ -117,6 +134,7 @@ class OverviewTab(QWidget):
             return lbl, val
 
         def _bar_row():
+            """Thêm một cặp nhãn–giá trị kèm thanh tiến độ (CPU, bộ nhớ)."""
             lbl, val = _pair()
             bar = QProgressBar()
             bar.setVisible(False)
@@ -132,6 +150,7 @@ class OverviewTab(QWidget):
 
     # ---- Audit Log preview --------------------------------------------------
     def _build_audit_section(self, root: QVBoxLayout, action_logs_tab_visible: bool) -> None:
+        """Dựng mục trích nhật ký kiểm toán; ẩn hẳn khi tab Nhật ký hành động bị tắt."""
         self.audit_group = QGroupBox()
         self.audit_group.setObjectName("monSection")
         audit_lay = QVBoxLayout(self.audit_group)
@@ -156,6 +175,10 @@ class OverviewTab(QWidget):
         self._refresh_budget()
 
     def _refresh_budget(self) -> None:
+        """Cập nhật thẻ ngân sách: còn lại / tổng, phần trăm đã dùng, cảnh báo khi vượt 85%.
+
+        Không ghi đè ô nhập khi người dùng đang gõ trong đó.
+        """
         from ....core import model_pricing as mp
         pricing = {**ut.DEFAULT_PRICING, **(self.ctx.config.data.get("usage") or {})}
         status = ut.budget_status(self.ctx.config)
@@ -175,6 +198,12 @@ class OverviewTab(QWidget):
 
     # ---- resource usage --------------------------------------------------------
     def _refresh_resource_usage(self) -> None:
+        """Đọc CPU/RAM/đĩa/mạng của CHÍNH tiến trình app.
+
+        Đĩa và mạng là tốc độ tức thời, tính bằng hiệu hai lần lấy mẫu chia cho
+        khoảng thời gian giữa chúng — nên lần đo đầu tiên luôn hiện "—". Không có
+        ``psutil`` thì cả mục chuyển sang "—" chứ không làm vỡ màn hình.
+        """
         try:
             import psutil
         except ImportError:
@@ -233,6 +262,7 @@ class OverviewTab(QWidget):
             self.network_val.setText(na)
 
     def _set_resource_na(self) -> None:
+        """Đặt mọi chỉ số tài nguyên về "—" (khi thiếu ``psutil``)."""
         na = tr("monitoring.na")
         self.cpu_bar.setValue(0)
         self.cpu_val.setText(na)
@@ -243,6 +273,7 @@ class OverviewTab(QWidget):
 
     # ---- usage cards -----------------------------------------------------------
     def _activity_line(self, event: dict) -> str:
+        """Một dòng hoạt động: dấu ✓/!/✗ theo kết quả, tên việc, và thời gian tương đối."""
         ok = event.get("ok", True)
         if ok:
             mark = f"<span style='color:{DOT_GREEN};'>✓</span>"
@@ -257,6 +288,11 @@ class OverviewTab(QWidget):
         return f"{mark} {name}{suffix}"
 
     def _refresh_usage_cards(self) -> None:
+        """Cập nhật các thẻ token và chi phí.
+
+        Đồng bộ bảng đơn giá trước rồi mới tính tiền, để con số chi phí luôn khớp
+        với bảng giá người dùng vừa sửa.
+        """
         from ....core import model_pricing as mp
         mp.sync_to_usage(self.ctx.config)   # cost total comes straight from the price table
         pricing = {**ut.DEFAULT_PRICING, **(self.ctx.config.data.get("usage") or {})}
@@ -297,6 +333,7 @@ class OverviewTab(QWidget):
             self.audit_lbl.setText(tr("monitoring.overview_no_activity"))
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho mọi tiêu đề mục và nhãn."""
         self.usage_group.setTitle(tr("monitoring.overview_usage_title").upper().replace("&", "&&"))
         self.budget_card.apply_btn.setToolTip(tr("usage.budget_apply_tooltip"))
         self.budget_card.budget_spin.setToolTip(tr("usage.budget_spin_tooltip"))
diff --git a/presentation/monitoring/tabs/pricing_panel.py b/presentation/monitoring/tabs/pricing_panel.py
index 4f55366..3724c62 100644
--- a/presentation/monitoring/tabs/pricing_panel.py
+++ b/presentation/monitoring/tabs/pricing_panel.py
@@ -19,7 +19,13 @@ from ....ui.icons import icon
 
 
 class PricingPanel(QGroupBox):
+    """Bảng đơn giá model trong màn Giám sát: nhập, xuất, tự dò và sửa tay.
+
+    Đơn giá ở đây là thứ Dashboard dùng để quy token ra tiền, nên sửa ở đây là
+    mọi con số chi phí trong app đổi theo.
+    """
     def __init__(self, ctx, on_status_message: Callable[[str], None]):
+        """Bảng đơn giá theo model, sửa được ngay tại chỗ."""
         super().__init__()
         self.ctx = ctx
         self._on_status_message = on_status_message
@@ -68,6 +74,7 @@ class PricingPanel(QGroupBox):
         self._reload_table()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, nút và tên cột."""
         self.setTitle(tr("monitoring.pricing_title").upper())
         self.ccy_lbl.setText(tr("monitoring.pricing_currency"))
         self.import_btn.setText(tr("monitoring.pricing_import"))
@@ -81,6 +88,7 @@ class PricingPanel(QGroupBox):
             tr("monitoring.pricing_col_output")])
 
     def _reload_table(self, *_a) -> None:
+        """Nạp lại toàn bộ bảng đơn giá từ cấu hình."""
         from ....core import model_pricing as mp
         to_ccy = self.ccy.currentData() or "USD"
         entries = mp.list_entries(self.ctx.config)
@@ -95,6 +103,7 @@ class PricingPanel(QGroupBox):
                 self.table.setItem(r, c, QTableWidgetItem(str(v)))
 
     def _import_pricing(self) -> None:
+        """Nhập đơn giá từ file Excel/CSV, gộp vào bảng hiện có."""
         from PySide6.QtWidgets import QFileDialog, QMessageBox
 
         from ....core import model_pricing as mp
@@ -117,6 +126,7 @@ class PricingPanel(QGroupBox):
         self._on_status_message(tr("monitoring.pricing_imported", n=len(imported)))
 
     def _export_pricing(self) -> None:
+        """Xuất file mẫu để điền đơn giá rồi nhập ngược lại."""
         from PySide6.QtWidgets import QFileDialog
 
         from ....core import model_pricing as mp
@@ -128,6 +138,7 @@ class PricingPanel(QGroupBox):
         self._on_status_message(tr("monitoring.pricing_exported"))
 
     def _add_pricing_row(self) -> None:
+        """Thêm một dòng đơn giá trống để người dùng điền tay."""
         from PySide6.QtWidgets import QInputDialog
 
         from ....core import model_pricing as mp
@@ -143,6 +154,7 @@ class PricingPanel(QGroupBox):
         self._reload_table()
 
     def _autolink_pricing(self) -> None:
+        """Nhờ AI dò đơn giá cho các model đang dùng mà chưa có giá, chạy ở luồng nền."""
         from ....core import model_pricing as mp
         from ....core.worker import AgentWorker
         if self._worker is not None:
@@ -152,9 +164,11 @@ class PricingPanel(QGroupBox):
         ccy = self.ccy.currentData() or "USD"
 
         def job(_w):
+            """Chạy nền: nhờ AI dò đơn giá cho các model đang dùng mà chưa có giá."""
             return {"entries": mp.auto_link(ctx, default_ccy=ccy)}
 
         def done(r):
+            """Đổ đơn giá vừa dò được vào bảng và lưu lại."""
             self._worker = None
             self.link_btn.setEnabled(True)
             self.ctx.save()
@@ -162,6 +176,7 @@ class PricingPanel(QGroupBox):
             self._on_status_message(tr("monitoring.pricing_linked", n=len(r.get("entries", []))))
 
         def failed(_e):
+            """Dò giá lỗi: chỉ mở khoá lại nút, giữ nguyên bảng đang có."""
             self._worker = None
             self.link_btn.setEnabled(True)
 
@@ -172,6 +187,7 @@ class PricingPanel(QGroupBox):
         w.start()
 
     def _delete_pricing_row(self) -> None:
+        """Xoá dòng đơn giá đang chọn."""
         from ....core import model_pricing as mp
         row = self.table.currentRow()
         entries = mp.list_entries(self.ctx.config)
diff --git a/presentation/monitoring/tabs/sandbox_tab.py b/presentation/monitoring/tabs/sandbox_tab.py
index 966055f..91a1b89 100644
--- a/presentation/monitoring/tabs/sandbox_tab.py
+++ b/presentation/monitoring/tabs/sandbox_tab.py
@@ -26,7 +26,11 @@ from .security_settings_tab import PermissionsCard
 
 
 class SandboxDetailsCard(QGroupBox):
+    """Thẻ "Trạng thái sandbox": backend cách ly đang dùng, giới hạn tài nguyên và
+    trạng thái chặn mạng.
+    """
     def __init__(self, ctx, on_settings_changed: Callable[[], None]):
+        """Thẻ thông tin sandbox: cơ chế cách ly đang dùng và các giới hạn của nó."""
         super().__init__()
         self._ctx = ctx
         self._on_settings_changed = on_settings_changed
@@ -77,6 +81,7 @@ class SandboxDetailsCard(QGroupBox):
         detail_lay.addWidget(self.permissions_card)
 
     def _open_settings(self) -> None:
+        """Mở hộp thoại Cài đặt tới nhóm an toàn, đóng xong thì làm mới thẻ."""
         open_settings_and_notify(self._ctx, self, self._on_settings_changed)
 
     def _sync_more_label(self, *_a) -> None:
@@ -85,6 +90,7 @@ class SandboxDetailsCard(QGroupBox):
         self.more_btn.setText(("▾ " if open_ else "▸ ") + tr("monitoring.overview_sbx_detail"))
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.setTitle(tr("monitoring.overview_sandbox_details_title").upper().replace("&", "&&"))
         self.id_lbl.setText(tr("monitoring.overview_sandbox_id"))
         self.status_lbl.setText(tr("monitoring.overview_status"))
@@ -96,6 +102,7 @@ class SandboxDetailsCard(QGroupBox):
         self._sync_more_label()
 
     def refresh(self) -> None:
+        """Đọc lại cấu hình an toàn và cập nhật các dòng trạng thái."""
         sec = self._ctx.config.agent_security
         net_blocked = bool(sec.get("block_network"))
 
diff --git a/presentation/monitoring/tabs/security_events_tab.py b/presentation/monitoring/tabs/security_events_tab.py
index 88c5fc2..4283eca 100644
--- a/presentation/monitoring/tabs/security_events_tab.py
+++ b/presentation/monitoring/tabs/security_events_tab.py
@@ -15,7 +15,13 @@ from ..shared.filter_scaffold import build_filter_scaffold
 
 
 class SecurityEventsTab(QWidget):
+    """Tab "Sự kiện bảo mật": các lượt bị chặn hoặc phải xin phê duyệt."""
     def __init__(self, ctx, on_refresh_all: Callable[[], None]):
+        """Tab Sự kiện bảo mật.
+
+        Bỏ cột Kết quả (mọi dòng đều là bị chặn) và thay bằng cột Hành động có tô
+        màu theo mức nghiêm trọng.
+        """
         super().__init__()
         self._ctx = ctx
         self._ai_state: dict = {}
@@ -34,9 +40,11 @@ class SecurityEventsTab(QWidget):
         self.detail_panel = parts["detail_panel"]
 
     def set_events(self, events: List[dict]) -> None:
+        """Đổ danh sách sự kiện vào bảng."""
         self.table.set_events(events)
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.table.retranslate()
         self.filter_edit.setPlaceholderText(tr("monitoring.filter_placeholder"))
         self.detail_panel.retranslate()
@@ -44,4 +52,5 @@ class SecurityEventsTab(QWidget):
         self.title_refresh_btn.setText(tr("monitoring.refresh"))
 
     def _start_ai_filter(self, search: QLineEdit, ai_btn: QPushButton) -> None:
+        """Nhờ AI dịch câu tìm kiếm tự nhiên thành từ khoá lọc."""
         start_ai_filter(self._ctx, search, ai_btn, self._ai_state)
diff --git a/presentation/monitoring/tabs/security_settings_tab.py b/presentation/monitoring/tabs/security_settings_tab.py
index 61ac36f..53c2c68 100644
--- a/presentation/monitoring/tabs/security_settings_tab.py
+++ b/presentation/monitoring/tabs/security_settings_tab.py
@@ -20,7 +20,9 @@ from ..shared.open_settings import open_settings_and_notify
 
 
 class PermissionsCard(QGroupBox):
+    """Thẻ "Quyền": agent đang được phép làm gì với tệp, mạng và lệnh shell."""
     def __init__(self, ctx, on_settings_changed: Callable[[], None]):
+        """Thẻ thiết lập quyền: agent được đụng tới gì mà không phải hỏi."""
         super().__init__()
         self._ctx = ctx
         self._on_settings_changed = on_settings_changed
@@ -38,9 +40,11 @@ class PermissionsCard(QGroupBox):
         perm_lay.addWidget(self.edit_btn, 0, Qt.AlignLeft)
 
     def _open_settings(self) -> None:
+        """Mở hộp thoại Cài đặt tới nhóm an toàn, đóng xong thì làm mới thẻ."""
         open_settings_and_notify(self._ctx, self, self._on_settings_changed)
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.setTitle(tr("monitoring.overview_permissions_title").upper())
         self.fs_lbl.setText(tr("monitoring.overview_perm_fs"))
         self.fs_val.setText(tr("monitoring.overview_perm_fs_value"))
@@ -52,6 +56,7 @@ class PermissionsCard(QGroupBox):
         self.edit_btn.setText(tr("monitoring.overview_edit"))
 
     def refresh(self) -> None:
+        """Đọc lại cấu hình an toàn và cập nhật các dòng quyền."""
         net_blocked = bool(self._ctx.config.agent_security.get("block_network"))
         self.network_val.setText(
             tr("monitoring.overview_perm_network_blocked") if net_blocked
diff --git a/presentation/monitoring/tabs/tools_admin_tab.py b/presentation/monitoring/tabs/tools_admin_tab.py
index dee2946..24b5361 100644
--- a/presentation/monitoring/tabs/tools_admin_tab.py
+++ b/presentation/monitoring/tabs/tools_admin_tab.py
@@ -43,6 +43,7 @@ _TOOL_ICON_NAME = {
 
 
 def _tool_icon_pixmap(name: str, size: int = 28) -> QPixmap:
+    """Vẽ icon tròn cho một thẻ công cụ."""
     pm = QPixmap(size, size)
     pm.fill(Qt.transparent)
     p = QPainter(pm)
@@ -59,6 +60,7 @@ def _tool_icon_pixmap(name: str, size: int = 28) -> QPixmap:
 
 
 def _clear_flow(flow: FlowLayout) -> None:
+    """Xoá sạch mọi widget trong một ``FlowLayout`` trước khi dựng lại."""
     while flow.count():
         item = flow.takeAt(0)
         w = item.widget()
@@ -67,7 +69,13 @@ def _clear_flow(flow: FlowLayout) -> None:
 
 
 class ToolsAdminTab(QWidget):
+    """Tab "Công cụ" trong màn Giám sát: bật/tắt từng tool dựng sẵn và tool MCP.
+
+    Tắt một tool ở đây là agent không còn được gọi nó nữa — danh sách tắt lưu
+    trong cấu hình dưới dạng ``tools_disabled``.
+    """
     def __init__(self, ctx: AppContext):
+        """Tab quản trị tool, chia thành các tab con theo nhóm tool."""
         super().__init__()
         self.ctx = ctx
         root = QVBoxLayout(self)
@@ -133,12 +141,14 @@ class ToolsAdminTab(QWidget):
 
     # ---- built-in tools card grid ---------------------------------------------
     def refresh(self) -> None:
+        """Vẽ lại toàn bộ lưới thẻ công cụ theo cấu hình mới nhất."""
         disabled = set(self.ctx.config.tools_disabled)
         _clear_flow(self._tool_flow)
         for spec in TOOL_SPECS:
             self._tool_flow.addWidget(self._tool_card(spec, spec.name not in disabled))
 
     def _tool_card(self, spec, enabled: bool) -> QWidget:
+        """Dựng một thẻ công cụ: icon, tên, mô tả và công tắc bật/tắt."""
         card = QFrame()
         card.setFrameShape(QFrame.NoFrame)
         style_card(card)
@@ -190,6 +200,7 @@ class ToolsAdminTab(QWidget):
         return card
 
     def _toggle_builtin(self, name: str, enabled: bool) -> None:
+        """Bật/tắt một tool dựng sẵn và ghi ngay vào cấu hình."""
         self.ctx.config.set_tool_enabled(name, enabled)
         # For fetch_url, the Enabled toggle also governs the runtime web-access
         # gate (agent_security.allow_url_fetch) — one control for the capability.
@@ -209,17 +220,20 @@ class ToolsAdminTab(QWidget):
             return
 
         def job(worker):
+            """Chạy nền: chẩn đoán kết nối Internet và tình trạng chứng chỉ TLS."""
             from ....core import tls_trust
             ok, message = tls_trust.diagnose_internet()
             return {"ok": ok, "message": message}
 
         def done(result):
+            """Hiện kết quả chẩn đoán, tô xanh/đỏ theo kết quả."""
             ok = result.get("ok")
             self.test_internet_status.setText(result.get("message", ""))
             self.test_internet_status.setStyleSheet("color: #090;" if ok else "color: #c00;")
             self.test_internet_btn.setEnabled(True)
 
         def failed(e):
+            """Chẩn đoán ném lỗi: hiện lỗi bằng màu đỏ."""
             self.test_internet_status.setText(str(e))
             self.test_internet_status.setStyleSheet("color: #c00;")
             self.test_internet_btn.setEnabled(True)
@@ -235,6 +249,7 @@ class ToolsAdminTab(QWidget):
 
     # ---- i18n -----------------------------------------------------------------
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn rồi vẽ lại lưới thẻ."""
         self.subtabs.setTabText(0, tr("tools_admin.subtab_tool"))
         self.subtabs.setTabText(1, tr("tools_admin.subtab_connector"))
         self._hint.setText(tr("tools_admin.hint"))
diff --git a/presentation/scheduling/ai_task_creator_dialog.py b/presentation/scheduling/ai_task_creator_dialog.py
index 47b9a01..7a73421 100644
--- a/presentation/scheduling/ai_task_creator_dialog.py
+++ b/presentation/scheduling/ai_task_creator_dialog.py
@@ -41,6 +41,12 @@ class AiTaskCreatorDialog(QDialog):
     description, or 📥 Import from a filled Excel/CSV/JSON file."""
 
     def __init__(self, ctx: AppContext, parent=None):
+        """Hộp thoại tạo task bằng AI hoặc nhập từ tệp.
+
+        Nhớ tab nào đang cấp danh sách task cho nút Đồng ý — hai tab cùng sinh ra
+        danh sách, không phân biệt thì bấm Đồng ý có thể tạo nhầm danh sách của tab
+        kia.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._planner = AiTaskPlannerService(provider_factory=ctx.build_active_provider)
@@ -82,6 +88,7 @@ class AiTaskCreatorDialog(QDialog):
 
     # ---- AI-gen tab -------------------------------------------------------
     def _build_ai_gen_page(self) -> QWidget:
+        """Dựng tab "Sinh bằng AI": ô mô tả, tệp/link đính kèm và nút sinh."""
         ai_page = QWidget()
         al = QVBoxLayout(ai_page)
         al.addWidget(QLabel(tr("schedtask.ai_desc_label")))
@@ -117,6 +124,7 @@ class AiTaskCreatorDialog(QDialog):
         return ai_page
 
     def _ai_pick_files(self) -> None:
+        """Chọn tệp đính kèm làm ngữ cảnh cho AI lập kế hoạch."""
         from PySide6.QtWidgets import QFileDialog
 
         files, _ = QFileDialog.getOpenFileNames(self, tr("schedtask.pick_files"))
@@ -125,12 +133,15 @@ class AiTaskCreatorDialog(QDialog):
             self.ai_files_edit.setText("; ".join(existing + files))
 
     def _attached_files(self) -> List[str]:
+        """Danh sách đường dẫn tệp đã nhập, tách theo dấu ``;``."""
         return [p.strip() for p in self.ai_files_edit.text().split(";") if p.strip()]
 
     def _attached_links(self) -> List[str]:
+        """Danh sách link đã nhập, tách theo dấu ``;``."""
         return [u.strip() for u in self.ai_links_edit.text().split(";") if u.strip()]
 
     def _generate(self) -> None:
+        """Nhờ AI tách mô tả thành nhiều task; đang chạy dở thì bỏ qua."""
         description = self.desc_edit.toPlainText().strip()
         if not description or self._worker is not None:
             return
@@ -139,6 +150,7 @@ class AiTaskCreatorDialog(QDialog):
         self.gen_btn.setText(tr("schedtask.ai_generating"))
 
         def job(worker: AgentWorker):
+            """Chạy nền: ghép mô tả với danh sách tệp/link rồi gọi bộ lập kế hoạch."""
             full_desc = description
             if files or links:
                 attach_note = "; ".join(files + links)
@@ -154,6 +166,7 @@ class AiTaskCreatorDialog(QDialog):
         w.start()
 
     def _on_planned(self, result: dict) -> None:
+        """Có kết quả: đổ danh sách task đề xuất ra bảng để người dùng xem lại."""
         self._worker = None
         self.gen_btn.setEnabled(True)
         self.gen_btn.setText(tr("schedtask.ai_generate"))
@@ -172,6 +185,7 @@ class AiTaskCreatorDialog(QDialog):
         self.buttons.button(QDialogButtonBox.Ok).setEnabled(bool(self._ai_planned))
 
     def _on_failed(self, err: str) -> None:
+        """Lập kế hoạch lỗi: trả nút về trạng thái bấm được và hiện lý do."""
         self._worker = None
         self.gen_btn.setEnabled(True)
         self.gen_btn.setText(tr("schedtask.ai_generate"))
@@ -179,12 +193,14 @@ class AiTaskCreatorDialog(QDialog):
 
     # ---- Import tab ---------------------------------------------------------
     def _on_import_tasks_changed(self, has_tasks: bool) -> None:
+        """Tab Nhập có task thì chuyển nguồn dữ liệu sang đó và mở nút OK."""
         if has_tasks:
             self._active_source = "import"
         self.buttons.button(QDialogButtonBox.Ok).setEnabled(has_tasks)
 
     # ---- confirm ------------------------------------------------------------
     def _confirm(self) -> None:
+        """Chốt: lấy task từ nguồn đang hoạt động (AI hoặc Nhập) và gắn project cho chúng."""
         planned = self.import_panel.planned if self._active_source == "import" else self._ai_planned
         project_id = self.workspace_combo.currentData() or ""
         for t in planned:
diff --git a/presentation/scheduling/ai_task_import_dialog.py b/presentation/scheduling/ai_task_import_dialog.py
index 6aabfe3..518923e 100644
--- a/presentation/scheduling/ai_task_import_dialog.py
+++ b/presentation/scheduling/ai_task_import_dialog.py
@@ -33,6 +33,7 @@ class _DropZone(QLabel):
     file_dropped = Signal(str)
 
     def __init__(self):
+        """Vùng kéo–thả tệp danh sách task."""
         super().__init__()
         from PySide6.QtCore import Qt
 
@@ -46,12 +47,14 @@ class _DropZone(QLabel):
         self.setAcceptDrops(True)
 
     def dragEnterEvent(self, event):  # noqa: N802
+        """Chỉ nhận tệp có đuôi hợp lệ."""
         urls = event.mimeData().urls()
         if urls and urls[0].toLocalFile().lower().endswith(
                 (".xlsx", ".xlsm", ".xls", ".csv", ".json")):
             event.acceptProposedAction()
 
     def dropEvent(self, event):  # noqa: N802
+        """Thả tệp: phát đường dẫn lên để panel đọc và dựng danh sách task."""
         urls = event.mimeData().urls()
         if urls:
             self.file_dropped.emit(urls[0].toLocalFile())
@@ -70,6 +73,7 @@ class ImportTaskPanel(QWidget):
     tasks_changed = Signal(bool)   # True when the current preview has >=1 valid task
 
     def __init__(self, planner: AiTaskPlannerService, parent=None):
+        """Panel nhập task từ tệp: xuất mẫu, chọn tệp, xem trước rồi mới tạo."""
         super().__init__(parent)
         self._planner = planner
         self.planned: List[dict] = []
@@ -96,6 +100,7 @@ class ImportTaskPanel(QWidget):
         il.addWidget(self.preview, 1)
 
     def _export_template(self) -> None:
+        """Xuất file mẫu Excel để người dùng điền danh sách task rồi nhập lại."""
         from PySide6.QtWidgets import QFileDialog
 
         from cowork_local.core.task_excel import export_template
@@ -112,6 +117,7 @@ class ImportTaskPanel(QWidget):
             QMessageBox.warning(self, tr("schedtask.tab_import"), str(exc))
 
     def _pick_import_file(self) -> None:
+        """Chọn file danh sách task để nhập."""
         from PySide6.QtWidgets import QFileDialog
 
         from cowork_local.core.task_import import IMPORT_FILTER
@@ -122,6 +128,9 @@ class ImportTaskPanel(QWidget):
             self._load_import_file(path)
 
     def _load_import_file(self, path: str) -> None:
+        """Đọc file và dựng danh sách task xem trước; file sai khuôn thì hiện lý do cụ
+        thể chứ không im lặng bỏ qua.
+        """
         try:
             self.planned = self._planner.import_file(path)
         except ValueError as exc:
diff --git a/presentation/scheduling/calendar_view_widget.py b/presentation/scheduling/calendar_view_widget.py
index 672c2b2..b745676 100644
--- a/presentation/scheduling/calendar_view_widget.py
+++ b/presentation/scheduling/calendar_view_widget.py
@@ -28,10 +28,12 @@ _WEEKDAY_KEYS = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
 
 
 class _DayCell(QFrame):
+    """Một ô ngày trên lưới lịch: số ngày, nút thêm task, và danh sách task của ngày đó."""
     add_requested = Signal(str)   # "YYYY-MM-DD"
     task_clicked = Signal(str)    # task_id
 
     def __init__(self):
+        """Một ô ngày trên lịch, chứa các task đến hạn hôm đó."""
         super().__init__()
         self.setObjectName("dayCell")
         self.setFrameShape(QFrame.StyledPanel)
@@ -56,6 +58,12 @@ class _DayCell(QFrame):
 
     def set_day(self, d: date, tasks: List[dict], dim: bool,
                 today: bool = False, weekend: bool = False) -> None:
+        """Vẽ lại ô cho một ngày cụ thể.
+
+        Chỉ "hôm nay" được nền tô đậm kèm viền nhấn; cuối tuần chỉ đổi nền chìm.
+        Nhờ vậy mắt bắt vào hôm nay trước, còn khối cuối tuần chỉ hiện ra khi
+        người dùng quét cả tháng. ``dim`` làm mờ ngày thuộc tháng khác.
+        """
         self._date_str = d.isoformat()
         self.date_lbl.setText(str(d.day))
         p = current_palette()
@@ -81,16 +89,23 @@ class _DayCell(QFrame):
             self.list.addItem(item)
 
     def _on_item_clicked(self, item: QListWidgetItem) -> None:
+        """Bấm vào một task trong ô: phát id lên để lớp trên mở trình sửa."""
         tid = item.data(Qt.UserRole)
         if tid:
             self.task_clicked.emit(tid)
 
 
 class CalendarView(QWidget):
+    """Khung nhìn Lịch của màn Lịch trình: xem theo tuần, tháng hoặc năm.
+
+    Widget này chỉ VẼ và phát tín hiệu; việc tạo/sửa task do vỏ
+    ``ScheduleTaskTab`` làm, vì Kanban cũng cần đúng hành vi đó.
+    """
     add_task_on_date = Signal(str)   # "YYYY-MM-DD"
     edit_task = Signal(str)          # task_id
 
     def __init__(self):
+        """Lịch xem task theo tháng/tuần/ngày, neo vào hôm nay."""
         super().__init__()
         self.granularity = "month"
         self.anchor = date.today()
@@ -131,6 +146,7 @@ class CalendarView(QWidget):
         self._retranslate()
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn rồi vẽ lại lưới."""
         self.today_btn.setText(tr("schedtask.cal_today"))
         self.prev_btn.setToolTip(tr("schedtask.cal_prev"))
         self.next_btn.setToolTip(tr("schedtask.cal_next"))
@@ -140,6 +156,7 @@ class CalendarView(QWidget):
 
     # ---- public ------------------------------------------------------
     def set_tasks(self, tasks: List[dict]) -> None:
+        """Nhận danh sách task mới và vẽ lại toàn bộ khung nhìn."""
         self._tasks = tasks
         self._render()
 
@@ -157,14 +174,17 @@ class CalendarView(QWidget):
 
     # ---- navigation ---------------------------------------------------
     def _shift(self, direction: int) -> None:
+        """Lùi/tiến một kỳ theo đúng độ mịn đang chọn (tuần, tháng hay năm)."""
         self.anchor = shift_period(self.anchor, self.granularity, direction)
         self._render()
 
     def _go_today(self) -> None:
+        """Nhảy về kỳ chứa ngày hôm nay."""
         self.anchor = date.today()
         self._render()
 
     def _on_granularity_changed(self) -> None:
+        """Đổi độ mịn tuần/tháng/năm và vẽ lại."""
         data = self.granularity_combo.currentData()
         if data:
             self.granularity = data
@@ -172,6 +192,11 @@ class CalendarView(QWidget):
 
     # ---- rendering ------------------------------------------------------
     def _clear_grid(self) -> None:
+        """Xoá sạch lưới trước khi vẽ lại.
+
+        Dùng ``deleteLater`` chứ không bỏ tham chiếu: widget Qt còn đang trong
+        hàng đợi sự kiện, xoá ngay có thể làm vỡ lúc đang xử lý sự kiện chuột.
+        """
         while self._grid.count():
             item = self._grid.takeAt(0)
             w = item.widget()
@@ -179,6 +204,7 @@ class CalendarView(QWidget):
                 w.deleteLater()
 
     def _render(self) -> None:
+        """Vẽ lại lưới theo độ mịn đang chọn: tuần, tháng (kèm ngày tràn) hoặc năm."""
         self._update_period_label()
         self._clear_grid()
         by_date = group_tasks_by_date(self._tasks)
@@ -191,6 +217,11 @@ class CalendarView(QWidget):
 
     def _render_days(self, days: List[date], by_date: Dict[str, List[dict]],
                      mark_month: Optional[int] = None) -> None:
+        """Vẽ lưới 7 cột: hàng đầu là tên thứ, các hàng sau là ô ngày.
+
+        ``mark_month`` là tháng "chính": ngày thuộc tháng khác bị làm mờ. Cột 5 và
+        6 là thứ Bảy và Chủ nhật vì ``_WEEKDAY_KEYS`` bắt đầu từ thứ Hai.
+        """
         for col, key in enumerate(_WEEKDAY_KEYS):
             lbl = QLabel(tr(f"schedtask.cal_weekday.{key}"))
             lbl.setStyleSheet("font-weight:600;")
@@ -210,6 +241,7 @@ class CalendarView(QWidget):
                 self._grid.addWidget(cell, r, c)
 
     def _render_year(self, by_date: Dict[str, List[dict]]) -> None:
+        """Xem theo năm: danh sách 12 tháng kèm số task, bấm vào là mở tháng đó."""
         counts = month_task_counts(by_date, self.anchor.year)
         lst = QListWidget()
         for m in range(1, 13):
@@ -223,6 +255,7 @@ class CalendarView(QWidget):
         self._grid.addWidget(lst, 0, 0)
 
     def _update_period_label(self) -> None:
+        """Cập nhật nhãn kỳ đang xem: khoảng ngày (tuần), năm, hoặc YYYY-MM (tháng)."""
         if self.granularity == "week":
             days = week_days(self.anchor)
             self.period_lbl.setText(f"{days[0].isoformat()} - {days[-1].isoformat()}")
diff --git a/presentation/scheduling/kanban_board_widget.py b/presentation/scheduling/kanban_board_widget.py
index c33e25d..cb8ebf9 100644
--- a/presentation/scheduling/kanban_board_widget.py
+++ b/presentation/scheduling/kanban_board_widget.py
@@ -52,6 +52,11 @@ class _KanbanColumn(QListWidget):
     task_dropped = Signal(str, str)   # task_id, new_status
 
     def __init__(self, status: str):
+        """Một cột Kanban ứng với một trạng thái task.
+
+        Cho chọn nhiều thẻ trong CÙNG một cột (Shift/Ctrl) để chuột phải xoá hàng
+        loạt, thay vì xoá từng cái.
+        """
         super().__init__()
         self.status = status
         self.setDragDropMode(QAbstractItemView.DragDrop)
@@ -68,6 +73,7 @@ class _KanbanColumn(QListWidget):
         self.setResizeMode(QListWidget.Adjust)   # re-wrap on every resize
 
     def dropEvent(self, event):  # noqa: N802
+        """Thả một thẻ từ lane khác sang: báo lên bảng để đổi trạng thái task."""
         source = event.source()
         if isinstance(source, _KanbanColumn) and source is not self:
             item = source.currentItem()
@@ -106,6 +112,11 @@ class KanbanBoardWidget(QWidget):
 
     def __init__(self, ctx, tasks_dir=None, scheduler=None,
                  service: Optional[TaskApplicationService] = None, parent=None):
+        """Bảng Kanban các task.
+
+        ``service`` để None thì tự dựng một cái từ kho task; ``scheduler`` để None
+        thì bảng chỉ đọc/ghi task chứ không chạy được cái nào.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._tasks_dir = tasks_dir
@@ -148,16 +159,23 @@ class KanbanBoardWidget(QWidget):
         scroll.viewport().installEventFilter(self)
 
     def retranslate(self) -> None:
+        """Áp lại tooltip của từng lane theo ngôn ngữ đang chọn."""
         for status, col in self.columns.items():
             col.setToolTip(tr(f"schedtask.col_tip.{status}"))
 
     # ---- lane widths ------------------------------------------------------
     def eventFilter(self, obj, event):  # noqa: N802
+        """Vùng cuộn đổi kích thước thì chia lại bề rộng cho 7 lane."""
         if obj is self._board_scroll.viewport() and event.type() == QEvent.Resize:
             self._fit_lanes()
         return super().eventFilter(obj, event)
 
     def _fit_lanes(self) -> None:
+        """Chia bề rộng cho 7 lane sao cho tất cả vừa một màn.
+
+        Có sàn tối thiểu tính theo bề rộng ký tự, để tiêu đề lane không bị cắt cụt
+        khi cửa sổ hẹp.
+        """
         floor = self.fontMetrics().averageCharWidth() * self._LANE_FLOOR_CH + 24
         for col in self.columns.values():
             if col.minimumWidth() != floor:
@@ -165,6 +183,7 @@ class KanbanBoardWidget(QWidget):
 
     # ---- rendering ----------------------------------------------------------
     def _card_text(self, t: dict) -> str:
+        """Chuỗi hiển thị trên một thẻ task: tiêu đề kèm mốc thời gian/độ ưu tiên."""
         prio = _PRIORITY_ICONS.get(t.get("priority", "medium"), "")
         ai = "[AI] " if t.get("is_ai_generated") else ""
         sched = t.get("schedule", {})
@@ -218,6 +237,7 @@ class KanbanBoardWidget(QWidget):
 
     # ---- actions --------------------------------------------------------
     def _on_double_click(self, item: QListWidgetItem) -> None:
+        """Bấm đúp một thẻ: mở trình sửa task đó."""
         tid = item.data(Qt.UserRole)
         if tid:
             self.edit_requested.emit(tid)
@@ -252,6 +272,10 @@ class KanbanBoardWidget(QWidget):
         return len(selected) > 1 and item in selected
 
     def _context_menu(self, col: _KanbanColumn, pos) -> None:
+        """Menu chuột phải trên một thẻ: chạy ngay, xem log, tạo task tiếp theo, xoá.
+
+        Đang chọn nhiều thẻ thì chuyển sang menu xoá hàng loạt.
+        """
         item = col.itemAt(pos)
         if item is None or not item.data(Qt.UserRole):
             return
@@ -300,6 +324,7 @@ class KanbanBoardWidget(QWidget):
                 self.refresh()
 
     def _bulk_delete_menu(self, col: _KanbanColumn, pos, selected) -> None:
+        """Menu xoá hàng loạt khi đang chọn nhiều thẻ."""
         menu = QMenu(col)
         del_act = menu.addAction(tr("schedtask.menu_delete_selected", n=len(selected)))
         chosen = menu.exec(col.viewport().mapToGlobal(pos))
@@ -320,6 +345,7 @@ class KanbanBoardWidget(QWidget):
         return True
 
     def _emit_run_now_message(self, result, title: str = "") -> None:
+        """Báo kết quả của lệnh "chạy ngay" ra thanh trạng thái."""
         if result is None:
             return
         if result.ok:
@@ -330,6 +356,7 @@ class KanbanBoardWidget(QWidget):
             self.status_message.emit(tr("schedtask.msg_no_scheduler"))
 
     def _view_logs(self, task: dict) -> None:
+        """Mở thư mục hiện vật chứa log của các lượt chạy task này."""
         from cowork_local.core.tasks import ARTIFACTS_DIR
 
         run_id = task.get("logs", {}).get("last_run_id")
diff --git a/presentation/scheduling/run_history_dialog.py b/presentation/scheduling/run_history_dialog.py
index 9fa2870..8e36ec5 100644
--- a/presentation/scheduling/run_history_dialog.py
+++ b/presentation/scheduling/run_history_dialog.py
@@ -18,6 +18,7 @@ class RunHistoryDialog(QDialog):
     double-click a row to open that run's artifact folder."""
 
     def __init__(self, task: dict, parent=None):
+        """Hộp thoại xem lịch sử các lần chạy của một task."""
         super().__init__(parent)
         self._task = task
         self.setWindowTitle(f"{tr('schedtask.menu_history')} — {task.get('title', '')}")
@@ -58,6 +59,7 @@ class RunHistoryDialog(QDialog):
         root.addWidget(buttons)
 
     def _open_artifact(self, item: QTableWidgetItem) -> None:
+        """Bấm một dòng: mở thư mục hiện vật của lượt chạy đó."""
         from cowork_local.core.tasks import ARTIFACTS_DIR
 
         first = self.table.item(item.row(), 0)
diff --git a/presentation/scheduling/schedule_task_tab.py b/presentation/scheduling/schedule_task_tab.py
index 6b19c91..96c4857 100644
--- a/presentation/scheduling/schedule_task_tab.py
+++ b/presentation/scheduling/schedule_task_tab.py
@@ -33,9 +33,22 @@ _VIEWS = ("kanban", "calendar")
 
 
 class ScheduleTaskTab(QWidget):
+    """Màn Lịch trình: phần vỏ ghép bảng Kanban và lịch tháng.
+
+    Vỏ giữ ba việc mà cả hai khung nhìn đều cần: thanh tiêu đề, nút chuyển
+    khung nhìn, và mở hộp thoại sửa task. Việc sửa task nằm ở đây (không ở
+    từng widget con) vì Kanban lẫn Lịch đều cần đúng một hành vi "mở trình
+    sửa cho task id này" — cả hai phát tín hiệu, vỏ mở hộp thoại.
+    """
     status_message = Signal(str)
 
     def __init__(self, ctx: AppContext, scheduler=None, tasks_dir: Optional[Path] = None):
+        """Vỏ màn Lịch task, ghép bảng Kanban và lịch.
+
+        ``tasks_dir`` để None thì dùng thư mục mặc định. Cho phép truyền vào là điểm
+        mới của R08-T11 — bản gộp cũ viết cứng, nên không test được nếu không đụng
+        thư mục cấu hình thật của người dùng.
+        """
         super().__init__()
         self.ctx = ctx
         self.scheduler = scheduler          # TaskScheduler (may be None in tests)
@@ -110,6 +123,7 @@ class ScheduleTaskTab(QWidget):
 
     # ---- i18n ------------------------------------------------------------
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, nút và tên hai khung nhìn."""
         self._title.setText(tr("schedtask.title"))
         self.add_btn.setText(tr("schedtask.add_btn"))
         self.add_btn.setToolTip(tr("schedtask.add_tooltip"))
@@ -122,24 +136,33 @@ class ScheduleTaskTab(QWidget):
 
     # ---- Kanban / Calendar view switch --------------------------------
     def _on_view_changed(self) -> None:
+        """Đổi khung nhìn Kanban ⇄ Lịch theo tab đang chọn."""
         self._view_stack.setCurrentIndex(self.view_tabs.currentIndex())
 
     def _on_counts_changed(self, counts: dict) -> None:
+        """Cập nhật dòng tóm tắt số task theo trạng thái.
+
+        Chỉ liệt kê trạng thái có task; đặt luôn tooltip để khi thanh bị co hẹp
+        người dùng vẫn đọc được đầy đủ.
+        """
         summary = "   ".join(
             f"{tr(f'schedtask.status.{s}')}: {counts[s]}" for s in STATUSES if counts[s])
         self.counts_lbl.setText(summary)
         self.counts_lbl.setToolTip(summary)   # full text stays reachable if clipped
 
     def refresh(self) -> None:
+        """Đọc lại toàn bộ task và vẽ lại cả Kanban lẫn Lịch."""
         all_tasks = self.kanban.refresh()
         self.calendar.set_tasks(all_tasks)
 
     # ---- task creation / editing (shared by Kanban + Calendar) -----------
     def _save_and_refresh(self, task: dict) -> None:
+        """Ghi task xuống đĩa rồi vẽ lại màn hình."""
         save_task(task, self._tasks_dir)
         self.refresh()
 
     def _add_task(self) -> None:
+        """Mở trình sửa để tạo task mới; chỉ lưu khi người dùng bấm xác nhận."""
         from cowork_local.ui.task_editor_dialog import TaskEditorDialog
 
         dlg = TaskEditorDialog(None, list_tasks(self._tasks_dir), self, ctx=self.ctx)
@@ -148,6 +171,9 @@ class ScheduleTaskTab(QWidget):
             self.status_message.emit(tr("schedtask.msg_created"))
 
     def _edit_task(self, task_id: str) -> None:
+        """Mở trình sửa cho một task đã có. Không tìm thấy id thì bỏ qua lặng lẽ
+        (task có thể vừa bị xoá ở khung nhìn khác).
+        """
         from cowork_local.ui.task_editor_dialog import TaskEditorDialog
 
         task = load_task(task_id, self._tasks_dir)
@@ -170,6 +196,7 @@ class ScheduleTaskTab(QWidget):
 
     # ---- AI create ----------------------------------------------------------
     def _ai_create(self) -> None:
+        """Mở hộp thoại nhờ AI lập kế hoạch, rồi lưu toàn bộ task nó sinh ra."""
         from cowork_local.presentation.scheduling.ai_task_creator_dialog import (
             AiTaskCreatorDialog,
         )
diff --git a/presentation/settings/general_settings_widget.py b/presentation/settings/general_settings_widget.py
index 6e0c3b0..45bc2b0 100644
--- a/presentation/settings/general_settings_widget.py
+++ b/presentation/settings/general_settings_widget.py
@@ -17,7 +17,11 @@ from ...ui.widgets import SegmentedControl, ToggleSwitch
 
 
 class GeneralSettingsWidget(QWidget):
+    """Nhóm "Chung" trong Cài đặt: ngôn ngữ, giao diện, khởi động cùng hệ thống,
+    thu về khay.
+    """
     def __init__(self, ctx, parent=None):
+        """Nhóm Cài đặt chung: ngôn ngữ, giao diện, thư mục dùng chung."""
         super().__init__(parent)
         data = ctx.config.data
         outer = QVBoxLayout(self)
@@ -58,6 +62,11 @@ class GeneralSettingsWidget(QWidget):
     # ---- lưu ------------------------------------------------------------
 
     def apply_to(self, data: dict) -> None:
+        """Ghi các lựa chọn chung vào dict cấu hình.
+
+        Không tự áp theme ở đây: ``MainWindow._open_settings`` áp lại sau khi hộp
+        thoại đóng, làm cả hai chỗ sẽ vẽ lại giao diện hai lần.
+        """
         data["language"] = self.language_combo.currentData()
         # MainWindow._open_settings áp lại giao diện sau khi dialog đóng, nên
         # ghi giá trị ở đây là đủ để nó có hiệu lực.
@@ -68,6 +77,7 @@ class GeneralSettingsWidget(QWidget):
 
 
 def _select(combo, value: str) -> None:
+    """Chọn mục mang dữ liệu ``value`` trong một combo; không có thì để nguyên."""
     i = combo.findData(value)
     if i >= 0:
         combo.setCurrentIndex(i)
diff --git a/presentation/settings/parameter_settings_widget.py b/presentation/settings/parameter_settings_widget.py
index 8077c97..560963d 100644
--- a/presentation/settings/parameter_settings_widget.py
+++ b/presentation/settings/parameter_settings_widget.py
@@ -15,13 +15,18 @@ from ...i18n import tr
 
 
 class ParameterSettingsWidget(QGroupBox):
+    """Nhóm "Tham số" trong Cài đặt: hạn mức token cho tệp đính kèm, ngữ cảnh,
+    số lượt song song và các ngưỡng khác.
+    """
     def __init__(self, ctx, parent=None):
+        """Nhóm Tham số: giới hạn token, ngưỡng rủi ro và các mức chặn của agent."""
         super().__init__(tr("settings.group.parameter"), parent)
         data = ctx.config.data
         sec = ctx.config.agent_security
         form = QFormLayout(self)
 
         def tieu_de(key: str) -> None:
+            """Thêm một dòng tiêu đề phụ vào form."""
             lbl = QLabel(tr(key))
             lbl.setStyleSheet("font-weight:600; margin-top:6px;")
             form.addRow(lbl)
@@ -75,6 +80,10 @@ class ParameterSettingsWidget(QGroupBox):
     # ---- lưu ------------------------------------------------------------
 
     def apply_to(self, data: dict) -> None:
+        """Ghi các tham số từ form vào dict cấu hình.
+
+        Ô nhập tính bằng NGHÌN token cho dễ đọc, nên phải nhân 1000 khi lưu.
+        """
         att = data.setdefault("attachments", {})
         att["max_tokens"] = self.attach_tokens.value() * 1000
         att["max_files"] = self.attach_files.value()
@@ -90,6 +99,7 @@ class ParameterSettingsWidget(QGroupBox):
 
 
 def _gioi_han(suffix: str, value: int, hi: int = 1_000_000) -> QSpinBox:
+    """Ô nhập số nguyên có hậu tố đơn vị, chặn trong khoảng 0..``hi``."""
     box = QSpinBox()
     box.setRange(0, hi)
     box.setSuffix(suffix)
diff --git a/presentation/settings/provider_settings_widget.py b/presentation/settings/provider_settings_widget.py
index 0b8ee20..be6ba0c 100644
--- a/presentation/settings/provider_settings_widget.py
+++ b/presentation/settings/provider_settings_widget.py
@@ -24,7 +24,18 @@ from ...ui.icons import icon
 
 
 class ProviderSettingsWidget(QGroupBox):
+    """Nhóm "Nhà cung cấp AI" trong hộp thoại Cài đặt.
+
+    Giữ một BẢN NHÁP riêng cho từng provider (``_staging``): đổi qua lại giữa
+    các provider trong lúc chỉnh không được làm mất thứ vừa gõ, và chỉ khi
+    bấm Lưu mới ghi xuống cấu hình thật.
+    """
     def __init__(self, ctx, parent=None):
+        """Nhóm Provider: endpoint, khoá API và model của từng provider.
+
+        Sửa trên một bản nháp (``_staging``) chứ không sửa thẳng cấu hình: người dùng
+        bấm Huỷ thì mọi thay đổi biến mất, kể cả khoá API vừa gõ.
+        """
         super().__init__(tr("settings.group.provider"), parent)
         self.ctx = ctx
         data = ctx.config.data
@@ -60,6 +71,7 @@ class ProviderSettingsWidget(QGroupBox):
     # ---- lưu ------------------------------------------------------------
 
     def apply_to(self, data: dict) -> None:
+        """Ghi provider đang chọn và toàn bộ bản nháp vào dict cấu hình."""
         data["active_provider"] = self.provider_combo.currentData()
         self._stash()
         for key, staged in self._staging.items():
@@ -72,6 +84,7 @@ class ProviderSettingsWidget(QGroupBox):
     # ---- bản nháp từng provider -----------------------------------------
 
     def _stash(self) -> None:
+        """Cất nội dung đang gõ vào bản nháp của provider hiện tại."""
         self._staging.setdefault(self._current_key, {}).update({
             "base_url": self.prov_base.text().strip(),
             "api_key": self.prov_key.text(),
@@ -79,6 +92,7 @@ class ProviderSettingsWidget(QGroupBox):
         })
 
     def _on_provider_changed(self) -> None:
+        """Đổi provider: cất bản nháp cũ rồi nạp bản nháp mới lên các ô nhập."""
         self._stash()
         self._current_key = self.provider_combo.currentData()
         conf = self._staging.get(self._current_key, {})
@@ -93,6 +107,11 @@ class ProviderSettingsWidget(QGroupBox):
         self.prov_status.setText("")
 
     def _conf_hien_tai(self, provider: str) -> dict:
+        """Cấu hình dùng để thử kết nối/nạp model.
+
+        Provider đang mở thì lấy thẳng từ ô nhập (kể cả thứ chưa lưu); provider
+        khác thì lấy từ bản nháp đã cất.
+        """
         if provider == self._current_key:
             return {"base_url": self.prov_base.text().strip(),
                     "api_key": self.prov_key.text(),
@@ -104,6 +123,7 @@ class ProviderSettingsWidget(QGroupBox):
     # ---- hàng model + hai nút -------------------------------------------
 
     def _hang_model(self) -> QWidget:
+        """Dựng hàng "Model": ô chọn model kèm nút nạp danh sách và nút thử kết nối."""
         row = QWidget()
         lay = QHBoxLayout(row)
         lay.setContentsMargins(0, 0, 0, 0)
@@ -132,15 +152,22 @@ class ProviderSettingsWidget(QGroupBox):
     # ---- việc chạy nền ---------------------------------------------------
 
     def _load_models(self, provider: str) -> None:
+        """Nạp danh sách model của provider ở luồng nền.
+
+        Giữ nguyên model đang chọn ở đầu danh sách, kể cả khi máy chủ không trả
+        về nó — người dùng có thể đang dùng một model không được liệt kê.
+        """
         conf = self._conf_hien_tai(provider)
         combo, status = self.prov_model, self.prov_status
 
         def job(worker):
+            """Chạy nền: hỏi provider danh sách model."""
             from ...providers import build_provider
             prov = build_provider(provider, conf)
             return {"models": prov.list_models(), "error": getattr(prov, "last_error", "")}
 
         def done(result):
+            """Đổ danh sách vào ô chọn, giữ model đang chọn ở đầu."""
             models = result.get("models") or []
             current = combo.currentText().strip()
             combo.clear()
@@ -163,25 +190,34 @@ class ProviderSettingsWidget(QGroupBox):
                        tr("settings.loading_models"))
 
     def _test_connection(self, provider: str) -> None:
+        """Thử kết nối tới provider ở luồng nền, tô xanh/đỏ kết quả."""
         conf = self._conf_hien_tai(provider)
         status = self.prov_status
 
         def job(worker):
+            """Chạy nền: gọi thử provider để xác nhận kết nối."""
             from ...providers import build_provider
             ok, message = build_provider(provider, conf).test_connection()
             return {"ok": ok, "message": message}
 
         def done(result):
+            """Hiện kết quả thử, tô xanh khi thành công và đỏ khi thất bại."""
             status.setText(result.get("message", ""))
             status.setStyleSheet("color: #090;" if result.get("ok") else "color: #c00;")
 
         def failed(e):
+            """Thử kết nối ném lỗi: hiện lỗi bằng màu đỏ."""
             status.setText(str(e))
             status.setStyleSheet("color: #c00;")
 
         self._chay_nen(job, done, failed, tr("settings.testing_connection"))
 
     def _chay_nen(self, job, done, failed, dang_lam: str) -> None:
+        """Chạy một việc ở luồng nền và hiện dòng trạng thái trong lúc chờ.
+
+        Giữ tham chiếu tới worker trong ``self._workers``: để nó bị thu gom giữa
+        chừng là luồng chết lặng lẽ, không lỗi, không kết quả.
+        """
         w = AgentWorker(job)
         w.finished_ok.connect(done)
         w.failed.connect(failed)
@@ -192,6 +228,12 @@ class ProviderSettingsWidget(QGroupBox):
 
 
 def _model_combo(value: str) -> QComboBox:
+    """Ô chọn model cho phép gõ tay.
+
+    Ép co lại theo bề rộng được cấp: mặc định Qt cho combo rộng bằng mục dài
+    nhất, mà id model thì rất dài — hàng đó sẽ tràn ra ngoài hộp thoại và đẻ ra
+    thanh cuộn ngang (tệ hơn ở màn 125%/150%). Phần bung ra để popup lo.
+    """
     combo = QComboBox()
     combo.setEditable(True)
     # Mặc định combo rộng bằng mục dài nhất; id model thì dài, nên hàng này
@@ -207,6 +249,7 @@ def _model_combo(value: str) -> QComboBox:
 
 
 def _select(combo: QComboBox, value: str) -> None:
+    """Chọn mục mang dữ liệu ``value`` trong một combo; không có thì để nguyên."""
     i = combo.findData(value)
     if i >= 0:
         combo.setCurrentIndex(i)
diff --git a/presentation/settings/routing_settings_widget.py b/presentation/settings/routing_settings_widget.py
index de93e19..5a5890b 100644
--- a/presentation/settings/routing_settings_widget.py
+++ b/presentation/settings/routing_settings_widget.py
@@ -24,7 +24,11 @@ POLICY_KEYS = (("quality", "routing.policy_quality"), ("cost", "routing.policy_c
 
 
 class RoutingSettingsWidget(QGroupBox):
+    """Nhóm "Định tuyến model" trong Cài đặt: chế độ, chính sách, ngưỡng đổi và
+    cấu hình trọng tài chấm điểm.
+    """
     def __init__(self, ctx, parent=None):
+        """Nhóm Định tuyến: chế độ tự chọn model và các tham số thăm dò."""
         super().__init__(tr("routing.settings_group"), parent)
         self.ctx = ctx
         routing = ctx.config.routing
@@ -82,6 +86,7 @@ class RoutingSettingsWidget(QGroupBox):
     # ---- lưu ------------------------------------------------------------
 
     def apply_to(self, data: dict) -> None:
+        """Ghi cấu hình định tuyến từ form vào dict cấu hình."""
         r = data.setdefault("routing", {})
         r["switch_mode"] = self.mode.currentData()
         r["policy"] = self.policy.currentData()
@@ -114,6 +119,7 @@ class RoutingSettingsWidget(QGroupBox):
 
 
 def _select(combo: QComboBox, value: str) -> None:
+    """Chọn mục mang dữ liệu ``value`` trong một combo; không có thì để nguyên."""
     i = combo.findData(value)
     if i >= 0:
         combo.setCurrentIndex(i)
diff --git a/presentation/shell/bootstrap.py b/presentation/shell/bootstrap.py
index 797390a..6ed1431 100644
--- a/presentation/shell/bootstrap.py
+++ b/presentation/shell/bootstrap.py
@@ -34,6 +34,10 @@ def build_secret_store():
 
 
 def build_config(path: Path | None = None) -> JsonConfigRepository:
+    """Dựng repository cấu hình đã nối sẵn kho bí mật của hệ điều hành.
+
+    Đây là Composition Root: chỗ DUY NHẤT quyết định app chạy bằng mảnh nào.
+    """
     return JsonConfigRepository.load(path, secrets=build_secret_store())
 
 
diff --git a/presentation/shell/lifecycle_coordinator.py b/presentation/shell/lifecycle_coordinator.py
index a3ce20a..b9c8fe6 100644
--- a/presentation/shell/lifecycle_coordinator.py
+++ b/presentation/shell/lifecycle_coordinator.py
@@ -27,13 +27,20 @@ MIN_W, MIN_H = 820, 520
 
 
 class LifecycleCoordinator:
+    """Vòng đời cửa sổ: canh vừa màn hình, theo dõi đổi màn hình, và quyết định
+    đóng cửa sổ là thoát hẳn hay thu về khay.
+    """
     def __init__(self, window):
+        """Theo dõi màn hình cửa sổ đang nằm trên, để khôi phục đúng vị trí và tỉ lệ khi
+        mở lại.
+        """
         self.window = window
         self._last_screen = None
 
     # ---- canh theo màn hình ----------------------------------------------
 
     def fit_to_screen(self, want_w: int, want_h: int) -> None:
+        """Canh cửa sổ vừa vùng làm việc của màn hình đang chứa nó."""
         w = self.window
         screen = w.screen() or QGuiApplication.primaryScreen()
         avail = screen.availableGeometry() if screen else None
@@ -73,6 +80,9 @@ class LifecycleCoordinator:
     def _apply_minimum(self, avail) -> None:
         # Kích thước tối thiểu không bao giờ được vượt quá thứ màn hình hiển
         # thị nổi — nếu không thì cửa sổ không thu nhỏ vừa màn được nữa.
+        """Đặt kích thước tối thiểu, nhưng không bao giờ vượt quá thứ màn hình hiển thị
+        nổi — vượt thì cửa sổ không thu nhỏ vừa màn được nữa.
+        """
         self.window.setMinimumSize(min(MIN_W, avail.width() - MARGIN),
                                    min(MIN_H, avail.height() - MARGIN))
 
diff --git a/presentation/shell/main_window.py b/presentation/shell/main_window.py
index 186228c..6397379 100644
--- a/presentation/shell/main_window.py
+++ b/presentation/shell/main_window.py
@@ -66,12 +66,18 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
     #: Biểu tượng khay, hoặc None nếu máy không có khay. Vẫn giữ tên cũ vì
     #: còn vài chỗ đọc thẳng self.tray; bản thân việc dựng/ẩn/thông báo đã
     #: chuyển sang self._tray (TrayManager).
+    """Cửa sổ chính: thanh menu trái, thanh trên, bốn trang nội dung và khay hệ thống.
+
+    Ghép từ nhiều mixin (thanh menu, bộ chọn project, thanh trên, sổ đăng ký
+    trang, sự kiện phiên) để mỗi phần nằm trong một file dưới trần 400 dòng.
+    """
     tray = property(lambda self: self._tray.icon)
 
     # Nav rows (Dashboard/Schedule/Monitoring are lazy; Workspace is the eager home page).
     _ROW_DASHBOARD, _ROW_SCHEDULE, _ROW_WORKSPACE, _ROW_MONITORING = 0, 1, 2, 3
 
     def __init__(self, ctx: AppContext, user_name: str = ""):
+        """Dựng cửa sổ chính: thanh điều hướng, các trang và biểu tượng khay."""
         super().__init__()
         self.ctx = ctx
         self._user_name = user_name
@@ -193,6 +199,11 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
         on_language_changed(self._retranslate)
 
     def resizeEvent(self, event):  # noqa: N802 - Qt override
+        """Đổi kích thước cửa sổ thì tính lại trần bề rộng thanh menu.
+
+        Trần là một tỉ lệ của cửa sổ nên phải tính lại ở đây; tính một lần lúc dựng
+        sẽ đọc phải kích thước của cửa sổ chưa được cấp phát.
+        """
         super().resizeEvent(event)
         # The rail's ceiling is a share of the window, so it moves with the
         # window. Computed once at construction it was read off a not-yet-sized
@@ -204,6 +215,7 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
             self.help_agent.reposition()
 
     def showEvent(self, event):  # noqa: N802 - Qt override
+        """Lần hiện đầu tiên: ghim lại trợ lý nổi cho đúng vị trí thật."""
         super().showEvent(event)
         if getattr(self, "help_agent", None) is not None:
             self._update_dock_guard()
@@ -217,6 +229,7 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
             QTimer.singleShot(3000, self._prewarm_graph)
 
     def _prewarm_graph(self) -> None:
+        """Dựng sẵn khung đồ thị GraphRAG lúc máy rảnh, để lần bấm đầu không giật."""
         view = getattr(self, "structure", None)
         if view is None or not hasattr(view, "prewarm"):
             return
@@ -268,11 +281,13 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
 
 
     def _show_window(self) -> None:
+        """Đưa cửa sổ trở lại từ khay hệ thống và kéo lên trước."""
         self.showNormal()
         self.raise_()
         self.activateWindow()
 
     def _quit_app(self) -> None:
+        """Thoát hẳn ứng dụng (khác với đóng cửa sổ về khay)."""
         self._really_quit = True
         self.close()
 
@@ -331,9 +346,11 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
     # panel. `want_*` stays the floor so a small screen behaves as before.
     # Canh cửa sổ và tắt sạch: presentation/shell/lifecycle_coordinator.py
     def _fit_to_screen(self, want_w: int, want_h: int) -> None:
+        """Canh cửa sổ vừa màn hình hiện tại."""
         self._life.fit_to_screen(want_w, want_h)
 
     def _on_screen_maybe_changed(self) -> None:
+        """Cửa sổ có thể đã sang màn hình khác: ghim lại trợ lý và tính lại bố cục."""
         if not self._life.screen_maybe_changed():
             return
         if getattr(self, "help_agent", None) is not None:
@@ -342,6 +359,9 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
 
 
     def moveEvent(self, event):  # noqa: N802 - Qt override
+        """Kéo cửa sổ sang màn hình khác thì vùng làm việc và tỉ lệ hiển thị có thể
+        khác — trợ lý nổi ghim lại, các pane quyết định lại xem còn vừa không.
+        """
         super().moveEvent(event)
         # Dragged to another monitor: its work area (and scaling) may differ, so
         # the floating assistant re-pins and the panes re-decide if they fit.
@@ -350,6 +370,10 @@ class MainWindow(NavRailMixin, RailProjectMixin, TopBarMixin,
 
     # ---- lifecycle ---------------------------------------------------
     def closeEvent(self, event) -> None:  # noqa: N802
+        """Đóng cửa sổ: thu về khay nếu cấu hình cho chạy nền, còn không thì thoát hẳn.
+
+        Chạy nền tiếp thì task theo lịch vẫn chạy và vẫn tự lưu.
+        """
         if self._life.should_keep_running():
             # Chạy nền tiếp: task vẫn chạy và vẫn tự lưu.
             event.ignore()
diff --git a/presentation/shell/nav_rail.py b/presentation/shell/nav_rail.py
index 5ad5c9c..20104db 100644
--- a/presentation/shell/nav_rail.py
+++ b/presentation/shell/nav_rail.py
@@ -351,11 +351,13 @@ class NavRailMixin:
         self._nav_wrap.setMaximumWidth(hi)
 
     def _on_split_moved(self, _pos: int, _index: int) -> None:
+        """Người dùng kéo thanh chia: nhớ lại bề rộng thanh menu để lần mở sau giữ nguyên."""
         if not self._nav_collapsed:
             self._nav_width = max(_NAV_MIN_WIDTH,
                                   min(self._nav_max_width(), self._nav_wrap.width()))
 
     def _toggle_nav(self) -> None:
+        """Thu gọn / mở rộng thanh menu, nhớ bề rộng trước khi thu để khôi phục đúng."""
         if not self._nav_collapsed:
             self._nav_width = max(_NAV_MIN_WIDTH,
                                   min(self._nav_max_width(), self._nav_wrap.width()))
diff --git a/presentation/shell/page_registry.py b/presentation/shell/page_registry.py
index 389b4c0..9a0605e 100644
--- a/presentation/shell/page_registry.py
+++ b/presentation/shell/page_registry.py
@@ -17,19 +17,31 @@ from ..scheduling.schedule_task_tab import ScheduleTaskTab
 
 
 class PageRegistryMixin:
-    def _page_index(self, widget) -> int:
-        return self.pages.indexOf(widget)
+    """Bốn màn chính của cửa sổ và cách chuyển giữa chúng.
+
+    Dashboard và Lịch dựng lười ở lần mở đầu tiên, nên MỌI đường tới một trang
+    phải đi qua :meth:`_goto` — đó là chỗ duy nhất gọi :meth:`_ensure_page`.
+    """
+
+    # Lớp này từng khai ``_page_index`` HAI lần: bản đầu chỉ gọi
+    # ``self.pages.indexOf(widget)`` và bị bản phía dưới che hoàn toàn (Python
+    # giữ định nghĩa sau cùng), tức là mã chết. Đã gỡ bản đầu; bản còn lại nằm
+    # ngay dưới ``_ensure_page`` và nó BẮT BUỘC phải so sánh danh tính trước,
+    # vì trang dựng lười vẫn còn là widget giữ chỗ cho tới lần mở đầu tiên.
     def _build_dashboard(self):
+        """Dựng màn Bảng điều khiển và nối dòng trạng thái của nó vào thanh dưới."""
         d = DashboardTab(self.ctx)
         d.status_message.connect(self.statusBar().showMessage)
         self.dashboard = d
         return d
     def _build_schedule(self):
+        """Dựng màn Lịch trình và nối dòng trạng thái của nó vào thanh dưới."""
         s = ScheduleTaskTab(self.ctx, self.task_scheduler)
         s.status_message.connect(self.statusBar().showMessage)
         self.schedule = s
         return s
     def _build_monitoring(self):
+        """Dựng màn Giám sát và nối dòng trạng thái của nó vào thanh dưới."""
         m = MonitoringTab(self.ctx, cowork=self.cowork, structure=self.structure,
                           task_scheduler=self.task_scheduler)
         m.status_message.connect(self.statusBar().showMessage)
@@ -50,6 +62,12 @@ class PageRegistryMixin:
         self._page_widgets[row] = real
         self._built[row] = True
     def _page_index(self, widget) -> int:
+        """Chỉ số trang của một widget.
+
+        So sánh theo danh tính trước khi hỏi ``QStackedWidget``: trang dựng lười
+        vẫn còn là widget giữ chỗ cho tới lần mở đầu tiên, nên ``indexOf`` một
+        mình sẽ trả về sai chỗ.
+        """
         if widget is self.workspace:
             return self._ROW_WORKSPACE
         if self.dashboard is not None and widget is self.dashboard:
@@ -60,6 +78,16 @@ class PageRegistryMixin:
             return self._ROW_MONITORING
         return self.pages.indexOf(widget)
     def _goto(self, page: int, sub) -> None:
+        """Chuyển sang một trang (và một sub-tab nếu có).
+
+        Gác cổng project được đặt ở đây chứ không ở từng nơi gọi: dòng trên thanh
+        menu bị làm mờ thì không bấm được, nhưng ``_goto`` còn được gọi từ RECENTS
+        và từ lúc khôi phục phiên — trước đây nó mở thẳng sub-tab mà cổng đang
+        đóng, thành ra trang hiện lên nhưng dải tab vẫn giấu nó đi.
+
+        Vệt sáng trên thanh menu cũng cập nhật ở đây, để nó đi theo NỘI DUNG chứ
+        không theo thứ vừa được bấm.
+        """
         self._ensure_page(page)                # build lazy page on first visit
         self.pages.setCurrentIndex(page)
         if page == self._ROW_WORKSPACE:
diff --git a/presentation/shell/rail_metrics.py b/presentation/shell/rail_metrics.py
index 6c5aaf7..5aa7d17 100644
--- a/presentation/shell/rail_metrics.py
+++ b/presentation/shell/rail_metrics.py
@@ -33,5 +33,10 @@ class _NavItemDelegate(QStyledItemDelegate):
     """
 
     def initStyleOption(self, option, index):
+        """Ép icon của thanh menu canh trái và canh giữa theo chiều dọc.
+
+        Mặc định Qt canh giữa icon theo chiều ngang, làm các dòng menu lệch nhau khi
+        thanh được thu gọn.
+        """
         super().initStyleOption(option, index)
         option.decorationAlignment = Qt.AlignLeft | Qt.AlignVCenter
diff --git a/presentation/shell/rail_project.py b/presentation/shell/rail_project.py
index 3fa0649..8be3ef6 100644
--- a/presentation/shell/rail_project.py
+++ b/presentation/shell/rail_project.py
@@ -69,6 +69,11 @@ class RailProjectMixin:
             act.triggered.connect(
                 lambda _checked=False, row=i: self.nav_project.setCurrentIndex(row))
     def _on_rail_project_pick(self, _idx: int) -> None:
+        """Chọn project ở thanh menu: chuyển workspace sang project đó.
+
+        Cờ ``_syncing_rail_project`` chặn vòng lặp khi chính workspace vừa đặt lại
+        bộ chọn này.
+        """
         if self._syncing_rail_project:
             return
         pid = self.nav_project.currentData()
@@ -110,6 +115,7 @@ class RailProjectMixin:
         self.nav_recents_hdr.setVisible(not self._nav_collapsed)
         self.nav_recents.setVisible(not self._nav_collapsed)
     def _on_rail_recent(self, item, _col: int = 0) -> None:
+        """Bấm một dòng trong mục GẦN ĐÂY: mở hội thoại đó, hoặc mở khung "Tất cả project…"."""
         data = item.data(0, Qt.UserRole) or {}
         if data.get("all"):
             self._goto(self._ROW_WORKSPACE, self.workspace._cowork_tab_idx)
@@ -129,4 +135,5 @@ class RailProjectMixin:
         self.workspace.start_new_chat()
         self._select_nav_row(self._ROW_WORKSPACE, self.workspace.current_subtab())
     def _nav_new_chat_enabled(self) -> bool:
+        """Nút "chat mới" chỉ bật khi đã có ít nhất một project."""
         return bool(self.workspace.project_choices())
diff --git a/presentation/shell/session_events.py b/presentation/shell/session_events.py
index dbc2d2d..8897747 100644
--- a/presentation/shell/session_events.py
+++ b/presentation/shell/session_events.py
@@ -19,6 +19,9 @@ from ...ui.workspace_tab import WorkspaceTab
 
 
 class SessionEventsMixin:
+    """Nối các sự kiện phiên chat vào vỏ cửa sổ: làm mới cột lịch sử, chấm trạng thái
+    và nhãn thư mục khi project đổi tên.
+    """
     def _running_session_ids(self):
         """All conversation ids currently running — interactive Cowork/Code
         chat tab AgentWorkers, plus Schedule Task runs (their own session,
@@ -33,6 +36,7 @@ class SessionEventsMixin:
         from PySide6.QtCore import QTimer
 
         def _do() -> None:
+            """Đồng bộ cột lịch sử với hội thoại đang mở và các hội thoại đang chạy."""
             current = self.cowork.session_id
             self.sidebar.set_view_state(current, self._running_session_ids())
             self.sidebar.refresh()
@@ -99,6 +103,7 @@ class SessionEventsMixin:
             except Exception:
                 pass
     def _on_projects_changed(self) -> None:
+        """Project được tạo/sửa/xoá: gom nhóm lại cột lịch sử và cập nhật nhãn thư mục."""
         self.sidebar.refresh()                 # History regroups by project
         self.cowork._apply_output_folder_label()  # project may have been renamed
         self.structure._refresh_project_combo()   # GraphRAG's project lock list follows too
diff --git a/presentation/shell/toast.py b/presentation/shell/toast.py
index 3a0b34c..fad75dd 100644
--- a/presentation/shell/toast.py
+++ b/presentation/shell/toast.py
@@ -16,6 +16,7 @@ class Toast(QLabel):
     """A small auto-hiding notification shown at the window's top-left."""
 
     def __init__(self, parent):
+        """Thông báo ngắn nổi lên rồi tự tắt; dựng ở trạng thái ẩn."""
         super().__init__(parent)
         self.setObjectName("toast")
         self.setWordWrap(True)
@@ -26,6 +27,7 @@ class Toast(QLabel):
         self._timer.timeout.connect(self.hide)
 
     def show_message(self, text: str, ok: bool = True, ms: int = 4500) -> None:
+        """Hiện một thông báo (xanh khi thành công, đỏ khi lỗi) rồi tự ẩn sau ``ms`` mili giây."""
         p = current_palette()
         bg = p.success_soft if ok else p.danger_soft
         fg = p.success if ok else p.danger
diff --git a/presentation/shell/top_bar.py b/presentation/shell/top_bar.py
index 36b2ae6..3f02be6 100644
--- a/presentation/shell/top_bar.py
+++ b/presentation/shell/top_bar.py
@@ -67,6 +67,7 @@ class TopBarMixin:
         self._account_row = self._build_account_row()
 
     def _build_topbar(self) -> QWidget:
+        """Dựng thanh trên: thương hiệu, bộ chọn provider/ngôn ngữ/theme và hàng tài khoản."""
         bar = QWidget()
         bar.setObjectName("topbar")
         # Styled centrally (see theme._TEMPLATE): flat, with a single hairline
@@ -173,6 +174,7 @@ class TopBarMixin:
         btn.setIcon(_icon(self._THEME_ICONS.get(self.ctx.config.theme, "monitor")))
         return btn
     def _set_theme(self, value: str) -> None:
+        """Đổi theme, ghi cấu hình và áp stylesheet mới lên toàn ứng dụng."""
         from ...ui.icons import icon as _icon
 
         self.ctx.config.theme = value
@@ -180,6 +182,9 @@ class TopBarMixin:
         self._apply_theme()
         self.theme_btn.setIcon(_icon(self._THEME_ICONS.get(value, "monitor")))
     def _on_provider_changed(self, _idx: int) -> None:
+        """Đổi provider đang dùng: lưu cấu hình rồi làm mới mọi bề mặt phụ thuộc nó
+        (tiêu đề Cowork, bộ chọn model của AI-Edit).
+        """
         self.ctx.config.active_provider = self.provider_combo.currentData()
         self.ctx.save()
         self.cowork.refresh_header()
@@ -191,6 +196,9 @@ class TopBarMixin:
                label=PROVIDER_LABELS.get(self.ctx.config.active_provider))
         )
     def _on_language_changed(self, _idx: int) -> None:
+        """Đổi ngôn ngữ giao diện; trùng ngôn ngữ hiện tại thì bỏ qua để không dựng lại
+        toàn bộ chữ vô ích.
+        """
         lang = self.language_combo.currentData()
         if not lang or lang == get_language():
             return
@@ -198,6 +206,7 @@ class TopBarMixin:
         self.ctx.save()
         set_language(lang)   # notifies every registered persistent widget
     def _open_settings(self) -> None:
+        """Mở hộp thoại Cài đặt; bấm Lưu thì áp lại theme và làm mới thanh trên."""
         dlg = SettingsDialog(self.ctx, self)
         if dlg.exec():
             self._apply_theme()
@@ -224,6 +233,7 @@ class TopBarMixin:
             self.sidebar.refresh()
             self.statusBar().showMessage(tr("app.status.settings_saved"))
     def _apply_theme(self) -> None:
+        """Áp theme đang cấu hình lên toàn bộ ứng dụng."""
         app = QApplication.instance()
         if app:
             set_active_theme(self.ctx.config.theme)
diff --git a/presentation/shell/tray_manager.py b/presentation/shell/tray_manager.py
index 7640d09..fe426fa 100644
--- a/presentation/shell/tray_manager.py
+++ b/presentation/shell/tray_manager.py
@@ -19,6 +19,9 @@ class TrayManager:
     """Khay hệ thống của một cửa sổ. An toàn khi máy không có khay."""
 
     def __init__(self, window, *, icon, tooltip: str, tr):
+        """Dựng biểu tượng khay nếu hệ điều hành có; không có thì mọi thao tác về sau
+        thành no-op.
+        """
         self.window = window
         self._tr = tr
         self.icon: QSystemTrayIcon | None = None
@@ -51,6 +54,7 @@ class TrayManager:
         self.icon.show()
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tooltip và menu khay."""
         if self.icon is not None:
             self.icon.setToolTip(self._tooltip)
         if self._open_act is not None:
@@ -58,6 +62,7 @@ class TrayManager:
             self._quit_act.setText(self._tr("app.tray.quit"))
 
     def hide(self) -> None:
+        """Ẩn biểu tượng khay; máy không có khay thì không làm gì."""
         if self.icon is not None:
             self.icon.hide()
 
diff --git a/providers/anthropic.py b/providers/anthropic.py
index 34b1edf..29962db 100644
--- a/providers/anthropic.py
+++ b/providers/anthropic.py
@@ -15,14 +15,24 @@ _MAX_RETRIES = 6  # auto-retry on rate-limit (429) / overloaded
 
 
 class AnthropicProvider(Provider):
+    """Adapter cho API Messages của Anthropic.
+
+    Khác OpenAI ở ba chỗ: prompt hệ thống nằm ở tham số ``system`` riêng chứ
+    không phải một tin nhắn, xác thực bằng header ``x-api-key``, và khối
+    nội dung là danh sách block chứ không phải chuỗi.
+    """
     name = "anthropic"
     supports_vision = True
 
     def _url(self) -> str:
+        """Endpoint ``/v1/messages``; mặc định là api.anthropic.com nếu không đặt ``base_url``."""
         base = str(self.conf.get("base_url") or "https://api.anthropic.com").rstrip("/")
         return f"{base}/v1/messages"
 
     def _headers(self) -> Dict[str, str]:
+        """Header cho một lượt gọi. Thiếu khoá thì báo lỗi ngay — Anthropic không
+        có chế độ chạy cục bộ không cần khoá như Ollama.
+        """
         key = self.conf.get("api_key")
         if not key:
             raise ProviderError("Anthropic API key is not configured.")
@@ -35,6 +45,12 @@ class AnthropicProvider(Provider):
     _FALLBACK_MODELS = ["claude-opus-4-8", "claude-sonnet-4-6", "claude-haiku-4-5-20251001"]
 
     def list_models(self):
+        """Danh sách model; hỏi được API thì dùng, không thì rơi về danh sách dựng sẵn.
+
+        Không bao giờ trả về rỗng: người dùng luôn phải chọn được một model, kể
+        cả khi mạng nội bộ chặn ``/v1/models``. Lý do thất bại ghi vào
+        ``last_error`` để giao diện hiện ra.
+        """
         self.last_error = ""
         base = str(self.conf.get("base_url") or "https://api.anthropic.com").rstrip("/")
         try:
@@ -58,6 +74,11 @@ class AnthropicProvider(Provider):
 
     @staticmethod
     def _split(messages: List[Dict[str, Any]]):
+        """Tách lịch sử thành (prompt hệ thống, danh sách tin nhắn) theo khuôn Anthropic.
+
+        Anthropic nhận prompt hệ thống ở một tham số riêng, nên mọi tin nhắn
+        role ``system`` phải được gom lại và bỏ khỏi danh sách.
+        """
         system_parts: List[str] = []
         api: List[Dict[str, Any]] = []
         for m in messages:
@@ -117,6 +138,12 @@ class AnthropicProvider(Provider):
         cancel: Optional[CancelFn] = None,
         on_reasoning: Optional[TextCallback] = None,
     ) -> Dict[str, Any]:
+        """Chạy một lượt chat có stream, có gọi tool, tự thử lại khi bị giới hạn tốc độ
+        hoặc máy chủ quá tải.
+
+        Giữ bản sao ``work`` của lịch sử để cắt bớt và gửi lại được khi tràn
+        context — không đụng vào danh sách của chỗ gọi.
+        """
         work = list(messages)   # local copy we can trim on context overflow
         payload: Dict[str, Any] = {
             "model": self.model,
@@ -324,6 +351,7 @@ class AnthropicProvider(Provider):
 
     @staticmethod
     def _error_text(resp: requests.Response) -> str:
+        """Rút câu lỗi dễ đọc từ phản hồi lỗi của Anthropic, kèm mã HTTP."""
         try:
             body = resp.json()
             msg = body.get("error", {}).get("message") or json.dumps(body)
diff --git a/providers/base.py b/providers/base.py
index b693a57..48c32c9 100644
--- a/providers/base.py
+++ b/providers/base.py
@@ -52,6 +52,9 @@ MODEL_NOT_FOUND_HINT = "\n→ Hãy chọn model khác trong ⚙ Settings rồi g
 
 
 def is_model_not_found_error(err: str) -> bool:
+    """``True`` khi thông báo lỗi là loại "không có model này" — chỗ gọi dựa vào
+    đây để gợi ý đổi model thay vì báo lỗi chung chung.
+    """
     return MODEL_NOT_FOUND_HINT in (err or "")
 
 
@@ -76,6 +79,7 @@ class CancelWatchdog:
     treats as a cancelled stream."""
 
     def __init__(self, resp, cancel: Optional[CancelFn], poll_secs: float = 0.15):
+        """Canh cờ huỷ trong lúc một lượt gọi HTTP đang chờ."""
         self._resp = resp
         self._cancel = cancel
         self._poll_secs = poll_secs
@@ -83,12 +87,21 @@ class CancelWatchdog:
         self._thread: Optional[threading.Thread] = None
 
     def __enter__(self) -> "CancelWatchdog":
+        """Bắt đầu canh. Không có hàm huỷ thì không dựng luồng nào — đây là đường đi
+        thường gặp nhất, không đáng tốn một luồng.
+        """
         if self._cancel is not None:
             self._thread = threading.Thread(target=self._watch, daemon=True)
             self._thread.start()
         return self
 
     def _watch(self) -> None:
+        """Luồng canh: thấy cờ huỷ là đóng thẳng response đang chờ.
+
+        Đóng socket là cách duy nhất cắt được một lượt stream đang treo — nếu chỉ
+        đặt cờ, ``iter_lines()`` vẫn chờ tới khi máy chủ gửi tiếp hoặc hết giờ.
+        Nhận cả ``Callable`` lẫn ``threading.Event`` để chỗ gọi khỏi phải đổi kiểu.
+        """
         while not self._done.is_set():
             # Support both Callable and threading.Event
             if hasattr(self._cancel, "is_set"):
@@ -104,6 +117,11 @@ class CancelWatchdog:
             self._done.wait(self._poll_secs)
 
     def __exit__(self, *exc_info) -> None:
+        """Dừng canh và chờ luồng thoát, tối đa 1 giây.
+
+        Có chờ, vì luồng canh còn giữ tham chiếu tới response; bỏ mặc nó thì đóng
+        kết nối xong luồng vẫn đang đọc.
+        """
         self._done.set()
         if self._thread is not None:
             self._thread.join(timeout=1.0)
@@ -130,24 +148,36 @@ class ThinkStreamSplitter:
     _CLOSE = "</think>"
 
     def __init__(self, on_text=None, on_reasoning=None):
+        """Tách dòng chữ model trả về thành phần suy nghĩ và phần trả lời.
+
+        Có bộ đệm riêng vì thẻ ``<think>`` có thể bị cắt làm đôi giữa hai gói dữ
+        liệu — xét từng gói rời rạc sẽ bỏ sót thẻ.
+        """
         self._on_text = on_text
         self._on_reasoning = on_reasoning
         self._buf = ""
         self._in_think = False
 
     def feed(self, piece: str) -> None:
+        """Đưa một mẩu vừa nhận từ luồng stream vào bộ tách."""
         if not piece:
             return
         self._buf += piece
         self._drain()
 
     def flush(self) -> None:
+        """Kết thúc luồng: đẩy nốt phần còn giữ lại trong bộ đệm.
+
+        Bắt buộc gọi khi stream đóng, nếu không phần đuôi đang giữ chờ ghép thẻ
+        ``<think>`` sẽ mất hẳn.
+        """
         if self._buf:
             self._emit(self._buf)
             self._buf = ""
 
     # -- internals -----------------------------------------------------
     def _emit(self, text: str) -> None:
+        """Gửi văn bản ra đúng callback tuỳ đang ở trong hay ngoài khối ``<think>``."""
         if not text:
             return
         cb = self._on_reasoning if self._in_think else self._on_text
@@ -163,6 +193,11 @@ class ThinkStreamSplitter:
         return 0
 
     def _drain(self) -> None:
+        """Rút bộ đệm, cắt tại mỗi thẻ mở/đóng và lật trạng thái.
+
+        Không tìm thấy thẻ thì vẫn giữ lại phần đuôi có thể là nửa thẻ viết dở
+        (``<thi``) — phát ra sớm là chữ rác lọt vào bong bóng trả lời.
+        """
         while self._buf:
             tag = self._CLOSE if self._in_think else self._OPEN
             idx = self._buf.lower().find(tag)
@@ -191,6 +226,7 @@ class ToolSpec:
     parameters: Dict[str, Any]
 
     def to_openai(self) -> Dict[str, Any]:
+        """Khai báo tool theo định dạng OpenAI function-calling."""
         return {
             "type": "function",
             "function": {
@@ -201,6 +237,7 @@ class ToolSpec:
         }
 
     def to_anthropic(self) -> Dict[str, Any]:
+        """Khai báo tool theo định dạng Anthropic — khác OpenAI ở tên khoá schema."""
         return {
             "name": self.name,
             "description": self.description,
@@ -218,6 +255,9 @@ class Provider:
     supports_vision = False
 
     def __init__(self, conf: Dict[str, Any]):
+        """``last_error`` được đặt khi ``list_models()`` hỏng, thay vì nuốt lỗi: màn Cài
+        đặt hiện nó ra để "không nạp được model" có một lý do cụ thể.
+        """
         self.conf = conf
         self.model = conf.get("model", "")
         # Set by list_models() on failure (network/auth/bad-response) instead of
@@ -399,6 +439,7 @@ class Provider:
 
     @staticmethod
     def _friendly_context_error(err: str) -> str:
+        """Đổi lỗi tràn context thành câu tiếng Việt nói rõ phải làm gì tiếp."""
         return (
             "Nội dung quá dài cho model này ngay cả sau khi tự nén lịch sử/cắt bớt "
             "tin nhắn. Hãy xoá bớt file đính kèm, chia nhỏ yêu cầu, hoặc đổi sang một "
@@ -406,6 +447,7 @@ class Provider:
         )
 
     def describe(self) -> str:
+        """Chuỗi ``provider:model`` để ghi log và hiện lên thanh trạng thái."""
         return f"{self.name}:{self.model}"
 
     # -- TLS: auto-recover from a self-signed/internal-CA gateway ------
diff --git a/providers/openai_compat.py b/providers/openai_compat.py
index 056425f..3b13a27 100644
--- a/providers/openai_compat.py
+++ b/providers/openai_compat.py
@@ -22,16 +22,28 @@ _MAX_RETRIES = 6      # auto-retry on rate-limit (429) up to this many times
 
 
 class OpenAICompatProvider(Provider):
+    """Adapter cho mọi endpoint nói giao thức OpenAI: gateway nội bộ, Ollama,
+    GitHub Copilot.
+
+    Một lớp dùng chung cho nhiều nhà cung cấp vì phần khác nhau giữa chúng
+    chỉ là ``base_url`` và cách gắn khoá — đều nằm trong ``conf``.
+    """
     name = "openai_compat"
     supports_vision = True
 
     def _url(self) -> str:
+        """Endpoint ``/chat/completions``. Chưa cấu hình ``base_url`` thì báo lỗi
+        ngay tại đây, thay vì để lỗi nổ ra ở tận tầng HTTP.
+        """
         base = str(self.conf.get("base_url", "")).rstrip("/")
         if not base:
             raise ProviderError("base_url is not configured for the OpenAI-compatible provider.")
         return f"{base}/chat/completions"
 
     def _headers(self) -> Dict[str, str]:
+        """Header cho một lượt gọi; không có khoá thì bỏ hẳn ``Authorization``
+        (Ollama chạy cục bộ không cần khoá).
+        """
         headers = {"Content-Type": "application/json"}
         key = self.conf.get("api_key")
         if key:
@@ -40,6 +52,11 @@ class OpenAICompatProvider(Provider):
 
     @staticmethod
     def _to_api_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Đổi lịch sử hội thoại nội bộ sang đúng khuôn OpenAI mong đợi.
+
+        Chỗ khác biệt thật sự là lượt gọi tool: bên trong app lưu một tin nhắn
+        assistant kèm ``tool_calls``, còn API đòi tham số phải là chuỗi JSON.
+        """
         out: List[Dict[str, Any]] = []
         for m in messages:
             role = m["role"]
@@ -89,6 +106,13 @@ class OpenAICompatProvider(Provider):
         cancel: Optional[CancelFn] = None,
         on_reasoning: Optional[TextCallback] = None,
     ) -> Dict[str, Any]:
+        """Chạy một lượt chat có stream, có gọi tool, tự thử lại khi bị giới hạn tốc độ.
+
+        Giữ một bản sao ``work`` của lịch sử để khi tràn context còn cắt bớt và
+        gửi lại được — không đụng vào danh sách của chỗ gọi. Suy luận nội bộ mà
+        gateway nhét thẳng vào ``content`` dưới dạng ``<think>…</think>`` được
+        tách ra qua ``ThinkStreamSplitter`` để bong bóng trả lời sạch.
+        """
         work = list(messages)   # local copy we can trim on context overflow
         payload: Dict[str, Any] = {"model": self.model, "stream": True}
         if tools:
@@ -104,6 +128,7 @@ class OpenAICompatProvider(Provider):
         # (rather than a separate reasoning_content field). Route that to
         # on_reasoning (→ "Thinking" indicator) and keep the answer bubble clean.
         def _emit_answer(t: str) -> None:
+            """Gom phần trả lời (đã tách khỏi khối suy luận) và đẩy dần ra ngoài."""
             text_parts.append(t)
             if on_text:
                 on_text(t)
@@ -302,6 +327,9 @@ class OpenAICompatProvider(Provider):
             pass
 
     def list_models(self):
+        """Danh sách model của gateway; lỗi thì trả về list rỗng và ghi lý do vào
+        ``last_error`` để giao diện hiện được thay vì im lặng.
+        """
         self.last_error = ""
         base = str(self.conf.get("base_url", "")).rstrip("/")
         if not base:
@@ -327,6 +355,12 @@ class OpenAICompatProvider(Provider):
 
     @staticmethod
     def _error_text(resp: requests.Response) -> str:
+        """Rút câu lỗi dễ đọc nhất từ phản hồi lỗi của gateway.
+
+        Mỗi gateway trả một khuôn khác nhau: chuẩn OpenAI là
+        ``{"error": {"message": ...}}``, có nơi trả phẳng với ``description`` mới
+        là câu dành cho người đọc còn ``message`` chỉ là "Not found".
+        """
         try:
             body = resp.json()
             # Prefer the OpenAI-style {"error": {"message": ...}} shape; some
@@ -353,6 +387,11 @@ class OpenAICompatProvider(Provider):
 
 
 def _assemble_assistant(text_parts: List[str], tool_acc: Dict[int, Dict[str, Any]]) -> Dict[str, Any]:
+    """Ghép các mẩu stream thành một tin nhắn assistant hoàn chỉnh.
+
+    Tham số tool về theo từng mẩu nên phải nối lại rồi mới parse; JSON hỏng
+    thì giữ nguyên chuỗi thô trong ``_raw`` thay vì làm vỡ cả lượt chat.
+    """
     tool_calls: List[Dict[str, Any]] = []
     for idx in sorted(tool_acc):
         slot = tool_acc[idx]
diff --git a/security/attachment_validator.py b/security/attachment_validator.py
index 2d58c17..9f23921 100644
--- a/security/attachment_validator.py
+++ b/security/attachment_validator.py
@@ -7,5 +7,6 @@ ATTACHMENT_DENIED_MESSAGE = "Attached content failed security validation."
 
 
 def validate_attachment(path: str, mime_type: str = "") -> bool:
+    """``True`` nếu tệp được phép đính kèm vào lượt chat."""
     result = classify_attachment(path, mime_type or None)
     return not result.blocked
\ No newline at end of file
diff --git a/security/audit_logger.py b/security/audit_logger.py
index 93e8946..b1e45d0 100644
--- a/security/audit_logger.py
+++ b/security/audit_logger.py
@@ -21,6 +21,12 @@ logger = logging.getLogger("cowork_local.security.audit")
 
 @dataclass
 class AuditEntry:
+    """Một dòng nhật ký kiểm toán, đủ trường để dựng lại bối cảnh sau này.
+
+    Cố ý KHÔNG lưu nguyên văn lệnh: chỉ giữ ``command_hash`` (SHA-256, 16
+    ký tự đầu) để đối chiếu hai lần chạy có giống nhau không, mà không đưa
+    nội dung nhạy cảm vào file log.
+    """
     timestamp: str = ""
     user: str = ""
     project: str = ""
@@ -38,6 +44,11 @@ class AuditEntry:
     approval_status: str = ""  # auto, approved, rejected
 
     def __post_init__(self):
+        """Điền mốc thời gian và mã băm lệnh nếu bên gọi chưa đặt.
+
+        Mã băm thay cho nội dung lệnh gốc: nhật ký cần truy được về sau nhưng không
+        nên chứa nguyên văn thứ đã chạy.
+        """
         if not self.timestamp:
             self.timestamp = datetime.now(timezone.utc).isoformat()
         if not self.command_hash and self.action_type:
@@ -47,6 +58,7 @@ class AuditEntry:
 
 
 def _audit_dir() -> Path:
+    """Thư mục chứa nhật ký kiểm toán. Import muộn để tránh vòng import với ``config``."""
     from ..config import CONFIG_DIR
     return CONFIG_DIR / "audit"
 
diff --git a/security/command_risk_classifier.py b/security/command_risk_classifier.py
index b8eaa7f..33eaf18 100644
--- a/security/command_risk_classifier.py
+++ b/security/command_risk_classifier.py
@@ -20,6 +20,11 @@ from typing import List, Optional
 
 
 class RiskLevel(str, Enum):
+    """Bậc rủi ro của một lệnh, prompt hay tệp đính kèm.
+
+    Kế thừa ``str`` để so sánh và ghi log thẳng bằng chuỗi mà không phải
+    ``.value`` ở từng chỗ dùng.
+    """
     SAFE = "safe"
     MODERATE = "moderate"
     HIGH = "high"
@@ -29,6 +34,11 @@ class RiskLevel(str, Enum):
 
 @dataclass
 class RiskResult:
+    """Kết quả một lần phân loại: điểm, bậc, lý do, và có chặn hẳn không.
+
+    ``reasons`` giữ lại đúng mẫu regex đã khớp — nhật ký kiểm toán phải trả
+    lời được "vì sao lệnh này bị chặn", không chỉ "bị chặn".
+    """
     score: int           # 0-100
     level: RiskLevel     # categorized bucket
     reasons: List[str]   # why this score was assigned
@@ -65,6 +75,13 @@ _MODERATE_PATTERNS = [
 
 
 def classify_command(command: str, is_cowork_mode: bool = True) -> RiskResult:
+    """Chấm điểm rủi ro một lệnh shell.
+
+    Ba tầng mẫu: ``_BLOCK_PATTERNS`` chặn thẳng (100 điểm, dừng ngay khi
+    khớp mẫu đầu tiên), ``_HIGH_PATTERNS`` và ``_MODERATE_PATTERNS`` cộng
+    dồn điểm. ``is_cowork_mode`` nới tay hơn cho màn Cowork, nơi người dùng
+    đang chủ động ngồi xem từng bước.
+    """
     score = 0
     reasons: List[str] = []
     blocked = False
@@ -114,10 +131,20 @@ def classify_command(command: str, is_cowork_mode: bool = True) -> RiskResult:
 
 
 def classify_prompt(prompt: str, is_cowork_mode: bool = True) -> RiskResult:
+    """Chấm điểm rủi ro một prompt — dùng chung bộ mẫu với lệnh shell.
+
+    Cố ý dùng chung: tấn công tiêm lệnh viết bằng văn xuôi ("ignore previous
+    instructions") và lệnh shell nguy hiểm đều nằm trong cùng danh sách mẫu.
+    """
     return classify_command(prompt, is_cowork_mode=is_cowork_mode)
 
 
 def classify_attachment(path: str, mime_type: Optional[str] = None) -> RiskResult:
+    """Chặn tệp đính kèm chạy được, theo đuôi tệp rồi tới kiểu MIME.
+
+    Chặn theo danh sách đen — mã nguồn và tệp thực thi không được đưa vào
+    ngữ cảnh chat. Tệp ngoài danh sách được coi là an toàn (30 điểm).
+    """
     import os
     _, ext = os.path.splitext(path.lower())
     blocked_ext = {
@@ -141,6 +168,11 @@ def classify_attachment(path: str, mime_type: Optional[str] = None) -> RiskResul
 
 
 def classify_action(action_type: str, action_details: Optional[dict] = None) -> RiskResult:
+    """Chấm điểm rủi ro một loại hành động theo từ khoá trong tên.
+
+    Hành động lạ nhận 50 điểm (mức trung bình) chứ không phải 0 — thứ chưa
+    biết thì không được mặc định là an toàn.
+    """
     a = action_type.lower()
     if any(kw in a for kw in ('execute', 'run', 'shell', 'system')):
         return RiskResult(70, RiskLevel.HIGH, [f"high: action '{action_type}'"])
diff --git a/state.py b/state.py
index 2e06293..976be01 100644
--- a/state.py
+++ b/state.py
@@ -37,6 +37,12 @@ class AppContext:
     """Holds the live config and small convenience factories."""
 
     def __init__(self, config: AppConfig):
+        """Dựng ngữ cảnh dùng chung cho cả ứng dụng: cấu hình, mốc khởi động và các
+        nguồn tool.
+
+        Vòng đời kết nối MCP nằm ở ``McpToolSourceManager`` chứ không ở đây — xem
+        docstring của nó về việc vì sao kiểm-rồi-tạo phải có khoá.
+        """
         self.config = config
         self.started_at = time.time()   # for Monitoring's Sandbox Details "Created"/"Uptime"
         # Admin-configured MCP servers + the built-in MS365 server (R05-T05):
@@ -71,6 +77,7 @@ class AppContext:
 
     @property
     def role(self) -> str:
+        """Vai trò người dùng. Bản này không có lớp xác thực nên luôn là 'admin'."""
         return "admin"  # no authentication layer, always full access
 
     # ---- Per-workspace modes (Auto Model Routing + Auto-run) ----------------
@@ -207,11 +214,13 @@ class AppContext:
         return build_provider(name, conf)
 
     def teams_notifier(self):
+        """Bộ gửi thông báo Teams, dựng theo webhook trong cấu hình."""
         from .core.teams import TeamsNotifier
 
         return TeamsNotifier(self.config.teams.get("webhook_url", ""), ca_bundle=self.config.ca_bundle)
 
     def save(self) -> None:
+        """Ghi cấu hình xuống đĩa."""
         self.config.save()
 
     # ---- 🔌 MCP Layer — external MCP servers this app connects to as a client
diff --git a/tests/integration/test_folder_tab.py b/tests/integration/test_folder_tab.py
index 9be67c4..e628d94 100644
--- a/tests/integration/test_folder_tab.py
+++ b/tests/integration/test_folder_tab.py
@@ -34,6 +34,26 @@ def qt_app():
     return QApplication.instance() or QApplication([])
 
 
+@pytest.fixture(autouse=True)
+def khong_goi_mang(monkeypatch):
+    """Chặn mọi lượt gọi mạng thật từ bộ chọn model của panel AI-Edit.
+
+    Mở panel AI-Edit sẽ gọi ``AiEditModelResolver.refresh()``, và hàm đó
+    dựng ``AgentWorker`` (QThread) đi hỏi ``list_models`` của provider qua
+    HTTP. Trong test, luồng nền đó sống lâu hơn chính test đã tạo ra nó:
+    nó vẫn đang chờ mạng khi test kết thúc, rồi vỡ giữa lúc thu gom rác ở
+    một test khác chạy sau — cả tiến trình pytest chết với
+    ``Windows fatal exception``, và chỗ báo lỗi không liên quan gì tới
+    nguyên nhân. Việc của module này là điều hướng và hiển thị, không phải
+    nạp danh sách model, nên vô hiệu hoá cả hai đường ra mạng.
+    """
+    from cowork_local.presentation.folder.ai_edit_model_resolver import AiEditModelResolver
+
+    monkeypatch.setattr(AiEditModelResolver, "refresh", lambda self: None)
+    monkeypatch.setattr(AiEditModelResolver, "_scan_all_image_models",
+                        lambda self, then_suggest=False: None)
+
+
 @pytest.fixture
 def ctx(qt_app, tmp_path: Path):
     return AppContext(AppConfig.load(tmp_path / "config.json"))
diff --git a/ui/accounts_tab.py b/ui/accounts_tab.py
index da4c0c8..69cb795 100644
--- a/ui/accounts_tab.py
+++ b/ui/accounts_tab.py
@@ -44,11 +44,15 @@ class _OrgTree(QTreeWidget):
     member_dropped = Signal(str, str)   # username, target_group_id ("" = ungrouped)
 
     def __init__(self):
+        """Bật kéo–thả ngay từ đầu; quyền kéo thật sự do :meth:`set_drag_enabled` quyết
+        định sau khi biết vai trò người đăng nhập.
+        """
         super().__init__()
         self.setDropIndicatorShown(True)
         self.setDragDropMode(QTreeWidget.DragDrop)
 
     def set_drag_enabled(self, enabled: bool) -> None:
+        """Cho phép hay cấm kéo–thả. Chỉ Admin mới được chuyển người giữa các nhóm."""
         self.setDragEnabled(enabled)
         self.setAcceptDrops(enabled)
 
@@ -63,17 +67,24 @@ class _OrgTree(QTreeWidget):
         return target_kind, source_kind
 
     def _drop_is_valid(self, event) -> bool:
+        """Chỉ nhận đúng một kiểu thả: một TÀI KHOẢN thả vào một NHÓM.
+
+        Mọi hướng khác (nhóm vào nhóm, tài khoản vào tài khoản) đều bị từ chối —
+        cây này biểu diễn quan hệ nhóm chứa người, không có cấp lồng nhau.
+        """
         target_kind, source_kind = self._drop_kinds(event)
         return bool(target_kind and target_kind[0] == "group"
                     and source_kind and source_kind[0] == "account")
 
     def dragEnterEvent(self, event) -> None:
+        """Nhận con trỏ kéo vào cây nếu đây là kiểu thả hợp lệ."""
         if self.dragEnabled() and self._drop_is_valid(event):
             event.acceptProposedAction()
         else:
             event.ignore()
 
     def dragMoveEvent(self, event) -> None:
+        """Cập nhật con trỏ khi rê qua từng mục — chỉ mục hợp lệ mới nhận."""
         if self._drop_is_valid(event):
             event.acceptProposedAction()
         else:
@@ -100,6 +111,12 @@ class AccountEditDialog(QDialog):
                 available_groups: Optional[List[groups.Group]] = None,
                 allow_role_edit: bool = True, allow_group_edit: bool = True,
                 fixed_group_id: str = ""):
+        """Dựng form thêm/sửa tài khoản.
+
+        ``account`` là None thì đây là form thêm mới. ``allow_role_edit`` và
+        ``allow_group_edit`` tắt cho Sub-admin: họ sửa được thành viên nhóm mình
+        nhưng không được tự nâng vai trò hay chuyển người sang nhóm khác.
+        """
         super().__init__(parent)
         self._existing = account
         self.setWindowTitle(tr("accounts.edit_title") if account else tr("accounts.add_title"))
@@ -140,6 +157,7 @@ class AccountEditDialog(QDialog):
         form.addRow(buttons)
 
     def result_fields(self) -> Dict[str, str]:
+        """Nội dung form dưới dạng dict, đã cắt khoảng trắng thừa."""
         return {
             "username": self.user_edit.text().strip(),
             "display_name": self.name_edit.text().strip(),
@@ -151,7 +169,16 @@ class AccountEditDialog(QDialog):
 
 
 class AccountsTab(QWidget):
+    """Màn Tài khoản: cây nhóm–người dùng, form sửa và bảng thống kê mức dùng.
+
+    Dữ liệu nằm ở thư mục dùng chung (OneDrive/ổ mạng) chứ không ở máy, nên mọi
+    máy trỏ vào cùng thư mục đều thấy chung một danh sách.
+
+    Phân quyền chạy xuyên suốt màn này: Admin thấy và sửa tất cả; Sub-admin chỉ
+    thấy nhóm của mình và chỉ sửa được thành viên thường trong đó.
+    """
     def __init__(self, ctx: AppContext):
+        """Dựng giao diện và nạp lần đầu."""
         super().__init__()
         self.ctx = ctx
         self._current_username = ""
@@ -275,24 +302,36 @@ class AccountsTab(QWidget):
 
     # ---- role-scoped repository access ---------------------------------
     def _shared_dir(self) -> str:
+        """Thư mục dùng chung đang cấu hình; '' nghĩa là chưa đặt và màn này không có
+        gì để hiện.
+        """
         return self.ctx.config.shared_dir
 
     def _accounts_dir(self):
+        """Thư mục chứa file tài khoản bên trong thư mục dùng chung."""
         return accounts.accounts_dir(self._shared_dir())
 
     def _groups_dir(self):
+        """Thư mục chứa file nhóm bên trong thư mục dùng chung."""
         return groups.groups_dir(self._shared_dir())
 
     def _is_admin(self) -> bool:
+        """Người đang đăng nhập có phải Admin không."""
         return self.ctx.role == "admin"
 
     def _my_group(self) -> Optional[groups.Group]:
+        """Nhóm của người đang đăng nhập; ``None`` nếu chưa đăng nhập hoặc chưa vào
+        nhóm nào.
+        """
         acc = self.ctx.account
         if acc is None:
             return None
         return groups.group_for_user(acc.username, self._groups_dir())
 
     def _visible_groups(self) -> List[groups.Group]:
+        """Các nhóm người đang đăng nhập được phép thấy — Admin thấy hết, còn lại chỉ
+        thấy nhóm của mình.
+        """
         all_groups = groups.list_groups(self._groups_dir())
         if self._is_admin():
             return all_groups
@@ -300,6 +339,11 @@ class AccountsTab(QWidget):
         return [mine] if mine else []
 
     def _visible_accounts(self) -> List[accounts.Account]:
+        """Các tài khoản người đang đăng nhập được phép thấy.
+
+        Lọc ngay tại đây chứ không lọc ở chỗ hiển thị: mọi thứ vẽ ra sau đó đều đi
+        qua hàm này, nên không có đường nào lộ tài khoản ngoài phạm vi.
+        """
         all_accounts = accounts.list_accounts(self._accounts_dir())
         if self._is_admin():
             return all_accounts
@@ -311,6 +355,9 @@ class AccountsTab(QWidget):
 
     # ---- tree ------------------------------------------------------------
     def refresh(self) -> None:
+        """Nạp lại cả cây và bảng thống kê. Chưa đặt thư mục dùng chung thì chỉ hiện
+        lời nhắc và để trống.
+        """
         shared_dir = self._shared_dir()
         if not shared_dir:
             self._shared_hint.setText(tr("accounts.no_shared_dir"))
@@ -336,6 +383,7 @@ class AccountsTab(QWidget):
         self.group_filter_combo.blockSignals(False)
 
     def _reload_tree(self) -> None:
+        """Dựng lại cây nhóm → thành viên từ dữ liệu trên đĩa."""
         self._reload_group_filter_combo()
         self.tree.clear()
         my_accounts = {a.username: a for a in self._visible_accounts()}
@@ -364,6 +412,11 @@ class AccountsTab(QWidget):
 
     def _add_account_item(self, parent: QTreeWidgetItem, acc: accounts.Account,
                           is_subadmin: bool = False) -> None:
+        """Thêm một dòng tài khoản vào dưới một nhóm.
+
+        Sub-admin được đánh dấu bằng biểu tượng ngôi sao thay vì ký tự ★ — ký tự
+        hiển thị khác nhau tuỳ phông của từng máy.
+        """
         label = f"{acc.display_name or acc.username} ({acc.username}) — {tr(f'accounts.role.{acc.role}')}"
         item = QTreeWidgetItem([label])
         if is_subadmin:   # subadmin badge → star icon instead of a ★ glyph
@@ -374,6 +427,7 @@ class AccountsTab(QWidget):
         parent.addChild(item)
 
     def _on_tree_select(self, *_a) -> None:
+        """Ghi nhớ tài khoản vừa chọn rồi vẽ lại (các nút sửa/xoá bật theo lựa chọn)."""
         item = self.tree.currentItem()
         kind_id = item.data(0, Qt.UserRole) if item else None
         self._current_username = kind_id[1] if kind_id and kind_id[0] == "account" else ""
@@ -381,6 +435,10 @@ class AccountsTab(QWidget):
 
     # ---- account CRUD ------------------------------------------------------
     def _add_account(self) -> None:
+        """Mở form thêm tài khoản rồi lưu.
+
+        Sub-admin bị khoá cứng vào nhóm của chính họ, không chọn được nhóm khác.
+        """
         shared_dir = self._shared_dir()
         if not shared_dir:
             return
@@ -417,11 +475,15 @@ class AccountsTab(QWidget):
         self.refresh()
 
     def _selected_account(self) -> Optional[accounts.Account]:
+        """Tài khoản đang chọn trên cây, đọc lại từ đĩa; ``None`` nếu không chọn dòng
+        tài khoản nào.
+        """
         if not self._current_username:
             return None
         return accounts.find_by_username(self._current_username, self._accounts_dir())
 
     def _edit_account(self) -> None:
+        """Mở form sửa tài khoản đang chọn rồi lưu."""
         account = self._selected_account()
         if account is None:
             return
@@ -457,6 +519,11 @@ class AccountsTab(QWidget):
         self.refresh()
 
     def _delete_account(self) -> None:
+        """Xoá tài khoản đang chọn, có hỏi lại.
+
+        Sub-admin chỉ xoá được thành viên thường — không xoá được Admin hay một
+        Sub-admin khác.
+        """
         account = self._selected_account()
         if account is None:
             return
@@ -473,6 +540,11 @@ class AccountsTab(QWidget):
         self.refresh()
 
     def _regenerate_code(self) -> None:
+        """Cấp lại mã đăng nhập mới cho tài khoản đang chọn và hiện mã ra một lần.
+
+        Mã mới phải khác mọi mã đang dùng, nên danh sách mã hiện có được truyền vào
+        hàm sinh mã.
+        """
         account = self._selected_account()
         if account is None:
             return
@@ -524,6 +596,7 @@ class AccountsTab(QWidget):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: nhờ model rút câu hỏi tự nhiên thành 1–3 từ khoá tìm kiếm."""
             provider = ctx.build_active_provider()
             reply = provider.chat([
                 {"role": "system", "content":
@@ -536,12 +609,16 @@ class AccountsTab(QWidget):
             return {"keyword": (reply.get("content") or "").strip().splitlines()[0][:60]}
 
         def done(result: dict) -> None:
+            """Đổ từ khoá vào ô tìm kiếm — chính việc gán chữ đã kích hoạt lọc lại cây."""
             self._ai_search_worker = None
             self.ai_search_btn.setEnabled(True)
             keyword = result.get("keyword") or query
             self.search_edit.setText(keyword)   # textChanged re-applies the filter
 
         def failed(_err: str) -> None:
+            """Gọi model hỏng thì lọc thẳng bằng câu người dùng gõ, không báo lỗi: tìm
+            kiếm là tiện ích, không đáng chặn người dùng.
+            """
             self._ai_search_worker = None
             self.ai_search_btn.setEnabled(True)
             self._apply_tree_filter(query)
@@ -554,6 +631,7 @@ class AccountsTab(QWidget):
 
     # ---- bulk import from Excel (Admin only) --------------------------------
     def _export_excel_template(self) -> None:
+        """Xuất file Excel mẫu để Admin điền danh sách tài khoản rồi nhập lại."""
         if not self._is_admin():
             return
         from ..core import account_excel
@@ -569,6 +647,9 @@ class AccountsTab(QWidget):
             QMessageBox.warning(self, tr("accounts.excel_template_btn"), str(exc))
 
     def _import_excel(self) -> None:
+        """Nhập tài khoản hàng loạt từ file Excel. Chỉ Admin, và phải đã đặt thư mục
+        dùng chung.
+        """
         if not self._is_admin() or not self._shared_dir():
             return
         from ..core import account_excel
@@ -598,6 +679,9 @@ class AccountsTab(QWidget):
 
     # ---- move a member between groups (Admin only, drag-and-drop) ---------
     def _on_member_dropped(self, username: str, target_group_id: str) -> None:
+        """Xử lý kéo một người sang nhóm khác: gỡ khỏi nhóm cũ, thêm vào nhóm mới rồi
+        lưu cả ba nơi (tài khoản, nhóm cũ, nhóm mới).
+        """
         if not self._is_admin():
             return
         account = accounts.find_by_username(username, self._accounts_dir())
@@ -616,6 +700,7 @@ class AccountsTab(QWidget):
 
     # ---- group CRUD (Admin only) -------------------------------------------
     def _add_group(self) -> None:
+        """Hỏi tên rồi tạo một nhóm mới. Chỉ Admin."""
         if not self._is_admin():
             return
         name, ok = QInputDialog.getText(self, tr("accounts.new_group_title"), tr("accounts.f_group_name"))
@@ -626,6 +711,7 @@ class AccountsTab(QWidget):
         self.refresh()
 
     def _add_member_to_group(self, group_id: str, username: str) -> None:
+        """Thêm một người vào danh sách thành viên của nhóm, bỏ qua nếu đã có."""
         g = groups.load_group(group_id, self._groups_dir())
         if g is None:
             return
@@ -634,6 +720,11 @@ class AccountsTab(QWidget):
             groups.save_group(g, self._groups_dir())
 
     def _remove_member_from_group(self, group_id: str, username: str) -> None:
+        """Gỡ một người khỏi nhóm.
+
+        Người bị gỡ mà đang là Sub-admin của nhóm thì phải xoá luôn vai trò ấy —
+        không thì nhóm còn trỏ tới một người không còn ở trong nó.
+        """
         g = groups.load_group(group_id, self._groups_dir())
         if g is None:
             return
@@ -647,9 +738,13 @@ class AccountsTab(QWidget):
 
     # ---- usage/cost table --------------------------------------------------
     def _pricing(self) -> Dict:
+        """Bảng đơn giá đang dùng: mặc định chồng bởi phần người dùng tự đặt trong cấu
+        hình.
+        """
         return {**ut.DEFAULT_PRICING, **(self.ctx.config.data.get("usage") or {})}
 
     def _reload_usage_table(self) -> None:
+        """Nạp lại bảng mức dùng theo kỳ đang chọn, gom sự kiện theo từng tài khoản."""
         shared_dir = self._shared_dir()
         period = self.period_combo.currentData() or "day"
         start = date.today() - timedelta(days=_PERIOD_DAYS.get(period, 1) - 1)
@@ -678,6 +773,7 @@ class AccountsTab(QWidget):
 
     # ---- i18n --------------------------------------------------------------
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho nhãn, nút và gợi ý."""
         self._shared_hint.setText(tr("accounts.no_shared_dir"))
         self.add_btn.setText(tr("accounts.add_btn"))
         self.edit_btn.setText(tr("accounts.edit_btn"))
diff --git a/ui/agent_manager_tab.py b/ui/agent_manager_tab.py
index c329cdc..e9104a8 100644
--- a/ui/agent_manager_tab.py
+++ b/ui/agent_manager_tab.py
@@ -30,6 +30,7 @@ class AgentManagerTab(QWidget):
     own, independent of any single Flow."""
 
     def __init__(self, ctx=None, parent=None):
+        """Dựng danh sách agent và form sửa."""
         super().__init__(parent)
         self.ctx = ctx               # for the AI "generate prompt from description" button
         self._gen_worker = None
@@ -124,6 +125,11 @@ class AgentManagerTab(QWidget):
 
     # ---- Agent (model) list, fetched live from the selected provider -----
     def _reload_models(self) -> None:
+        """Nạp danh sách model của provider đang chọn.
+
+        Model đang chọn được đưa vào danh sách trước, ngay trong lúc chờ: không thì
+        ô model trống trơn vài giây và người dùng tưởng lựa chọn của mình đã mất.
+        """
         if self.ctx is None:
             return
         provider_key = self.provider_combo.currentData() or self.ctx.config.active_provider
@@ -136,6 +142,7 @@ class AgentManagerTab(QWidget):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: hỏi provider danh sách model. Lỗi thì trả danh sách rỗng."""
             try:
                 return {"models": ctx.build_provider_for(provider_key).list_models() or [],
                         "provider": provider_key}
@@ -143,6 +150,9 @@ class AgentManagerTab(QWidget):
                 return {"models": [], "provider": provider_key}
 
         def done(result: dict) -> None:
+            """Đổ danh sách model vào bộ chọn; bỏ qua nếu provider đã bị đổi lần nữa trong
+            lúc chờ.
+            """
             if result.get("provider") != (self.provider_combo.currentData()
                                           or ctx.config.active_provider):
                 return   # provider changed again while fetching
@@ -166,6 +176,7 @@ class AgentManagerTab(QWidget):
 
     # ---- AI: draft the prompt from the short name/description -----------
     def _gen_prompt(self) -> None:
+        """Nhờ model viết nội dung prompt cho agent từ tên và mô tả."""
         name = self.name_edit.text().strip()
         desc = self.desc_edit.text().strip()
         if not name and not desc:
@@ -178,6 +189,7 @@ class AgentManagerTab(QWidget):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi model sinh prompt cho agent."""
             return {"prompt": generate_agent_prompt(
                 ctx.build_active_provider(), name, desc, worker.is_cancelled)}
 
@@ -188,17 +200,22 @@ class AgentManagerTab(QWidget):
         w.start()
 
     def _on_gen_prompt(self, result) -> None:
+        """Đổ prompt model vừa sinh vào ô soạn."""
         text = (result or {}).get("prompt", "")
         if text:
             self.prompt_edit.setPlainText(text)
         self._reset_gen_prompt_btn()
 
     def _reset_gen_prompt_btn(self) -> None:
+        """Bật lại nút sinh prompt và trả chữ về như cũ."""
         self._gen_prompt_btn.setEnabled(True)
         self._gen_prompt_btn.setText(tr("agentmgr.gen_prompt_btn"))
 
     # ---- list <-> editor ------------------------------------------------
     def _reload_list(self, select_name: str = "") -> None:
+        """Nạp lại danh sách agent, chọn lại đúng agent theo tên nếu có yêu cầu — dùng
+        sau khi lưu để con trỏ không nhảy về đầu danh sách.
+        """
         self.list.blockSignals(True)
         self.list.clear()
         agents = list_agents()
@@ -217,6 +234,7 @@ class AgentManagerTab(QWidget):
             self._clear_editor()
 
     def _current_agent(self) -> Optional[CustomAgent]:
+        """Agent đang chọn; ``None`` nếu chưa chọn dòng nào."""
         row = self.list.currentRow()
         agents = list_agents()
         if 0 <= row < len(agents):
@@ -224,6 +242,11 @@ class AgentManagerTab(QWidget):
         return None
 
     def _load_into_editor(self, _row: int) -> None:
+        """Đổ agent đang chọn vào form.
+
+        Model được nhớ riêng vào ``_pending_model`` vì danh sách model nạp bất đồng
+        bộ — không giữ lại thì lựa chọn biến mất khi danh sách về tới nơi.
+        """
         agent = self._current_agent()
         if agent is None:
             self._clear_editor()
@@ -240,6 +263,7 @@ class AgentManagerTab(QWidget):
         self.model_combo.setCurrentIndex(max(0, self.model_combo.findData(agent.model)))
 
     def _clear_editor(self) -> None:
+        """Xoá trắng form và bỏ tên đang mở."""
         self._loaded_name = ""
         self.name_edit.clear()
         self.desc_edit.clear()
@@ -249,11 +273,13 @@ class AgentManagerTab(QWidget):
         self.model_combo.setCurrentIndex(0)
 
     def _new_agent(self) -> None:
+        """Bỏ chọn trong danh sách và mở một form trống để tạo agent mới."""
         self.list.setCurrentRow(-1)
         self._clear_editor()
         self.name_edit.setFocus()
 
     def _save(self) -> None:
+        """Lưu agent đang soạn. Chưa nhập tên thì con trỏ nhảy vào ô tên, không lưu."""
         name = self.name_edit.text().strip()
         if not name:
             self.name_edit.setFocus()
@@ -270,6 +296,7 @@ class AgentManagerTab(QWidget):
         self._reload_list(select_name=agent.name)
 
     def _delete(self) -> None:
+        """Xoá agent đang chọn, có hỏi lại."""
         agent = self._current_agent()
         if agent is None:
             return
diff --git a/ui/co4e_agent_dialog.py b/ui/co4e_agent_dialog.py
index 92f371a..7012fda 100644
--- a/ui/co4e_agent_dialog.py
+++ b/ui/co4e_agent_dialog.py
@@ -21,7 +21,11 @@ from .icons import icon, icon_picker_combo
 
 
 class Co4EAgentDialog(QDialog):
+    """Hộp thoại tạo/sửa một agent tự tạo của Co4E: tên, vai trò, model, chỉ dẫn,
+    skill và tệp đính kèm.
+    """
     def __init__(self, ctx, agent: CustomAgent, skill_names: List[str], parent=None):
+        """Form thêm/sửa một agent Co4E: tên, prompt và các skill nó được dùng."""
         super().__init__(parent)
         self.ctx = ctx
         self._agent = agent
@@ -134,11 +138,13 @@ class Co4EAgentDialog(QDialog):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: nhờ model soạn thử phần chỉ dẫn cho agent."""
             from ..core.ai_task_planner import generate_agent_prompt
             return {"text": generate_agent_prompt(ctx.build_active_provider(), name, role, hint,
                                                   cancel=worker.is_cancelled)}
 
         def done(result: dict):
+            """Đổ chỉ dẫn vừa soạn vào ô soạn thảo."""
             self.gen_btn.setEnabled(True)
             if result.get("text"):
                 self.instructions_edit.setPlainText(result["text"])
@@ -150,6 +156,7 @@ class Co4EAgentDialog(QDialog):
         w.start()
 
     def _refresh_attach_list(self) -> None:
+        """Vẽ lại danh sách tệp đính kèm (chỉ hiện tên tệp, đường dẫn để trong tooltip)."""
         from pathlib import Path as _P
         self.attach_list.clear()
         for p in self._attachments:
@@ -158,6 +165,7 @@ class Co4EAgentDialog(QDialog):
             self.attach_list.addItem(item)
 
     def _add_attachment(self) -> None:
+        """Thêm tệp đính kèm cho agent."""
         from PySide6.QtWidgets import QFileDialog
         files, _ = QFileDialog.getOpenFileNames(self, tr("co4e.attach_add"))
         for f in files:
@@ -166,12 +174,18 @@ class Co4EAgentDialog(QDialog):
         self._refresh_attach_list()
 
     def _del_attachment(self) -> None:
+        """Gỡ tệp đính kèm đang chọn."""
         row = self.attach_list.currentRow()
         if 0 <= row < len(self._attachments):
             self._attachments.pop(row)
             self._refresh_attach_list()
 
     def result_agent(self) -> CustomAgent:
+        """Bản ghi agent dựng từ nội dung đang có trên form.
+
+        Vai trò luôn viết HOA và không bao giờ rỗng — prompt của bước dùng thẳng
+        chuỗi này nên để trống sẽ sinh ra câu cụt.
+        """
         a = self._agent
         a.name = self.name_edit.text().strip() or "Agent"
         a.role = (self.role_edit.text().strip() or "AGENT").upper()
@@ -187,6 +201,7 @@ class Co4EAgentDialog(QDialog):
         return a
 
     def _load_models(self) -> None:
+        """Nạp danh sách model đang sống vào ô chọn, ở luồng nền."""
         if self.ctx is None:
             return
         from ..core import preview_ai
@@ -196,9 +211,11 @@ class Co4EAgentDialog(QDialog):
         ctx = self.ctx
 
         def job(_w):
+            """Chạy nền: hỏi mọi provider danh sách model đang dùng được."""
             return preview_ai.fetch_live_models(ctx)
 
         def done(result: dict):
+            """Gộp model của mọi provider vào ô chọn, giữ nguyên thứ đang chọn."""
             self.load_btn.setEnabled(True)
             models = []
             for lst in (result or {}).values():
diff --git a/ui/co4e_tab.py b/ui/co4e_tab.py
index f44b3ec..dad7a05 100644
--- a/ui/co4e_tab.py
+++ b/ui/co4e_tab.py
@@ -71,6 +71,10 @@ class _EqualTabBar(QTabBar):
     _GAP = 6            # px between tabs — matches the QSS margin-right below
 
     def tabSizeHint(self, index):  # noqa: N802
+        """Chia đều bề rộng cho mọi tab thay vì để Qt co theo độ dài nhãn.
+
+        Nhãn dài ngắn khác nhau làm dải tab nhấp nhô mỗi khi đổi tên luồng.
+        """
         base = super().tabSizeHint(index)
         n = self.count() or 1
         avail = self.width()
@@ -81,6 +85,7 @@ class _EqualTabBar(QTabBar):
         return QSize(max(56, share), max(30, base.height()))
 
     def resizeEvent(self, e):  # noqa: N802
+        """Đổi bề rộng dải tab thì tính lại bề rộng từng tab."""
         super().resizeEvent(e)
         self.updateGeometry()                # re-hint tab widths when resized
 
@@ -103,9 +108,20 @@ class Co4ETab(
         Co4ERunsMixin,
         Co4EChatMixin,
         QWidget):
+    """Màn Co4E Studio, ghép từ 7 mixin: dải tab luồng, cột trái, bố cục, CRUD luồng,
+    quản lý agent, chạy luồng, và khung chat.
+
+    Tách thành mixin để mỗi phần nằm trong một file dưới trần 400 dòng; thứ tự
+    kế thừa quan trọng — xem ghi chú ở đầu từng file mixin.
+    """
     status_message = Signal(str)
 
     def __init__(self, ctx):
+        """Dựng Co4E Studio: khung vẽ workflow, cột nguyên liệu và bảng Flow Status.
+
+        Mở sẵn một workflow trống để người dùng kéo bước vào ngay, không phải bấm
+        "tạo mới" trước.
+        """
         super().__init__()
         self.ctx = ctx
         self._wf: co4e.Workflow = co4e.new_workflow(tr("co4e.untitled"))
@@ -217,9 +233,10 @@ class Co4ETab(
     # history pane beside it), so the threshold is about its own screen only.
     _NARROW = 1300
 
-    def showEvent(self, e):  # noqa: N802 - Qt override
-        super().showEvent(e)
-        self._narrow_guard.attach()
+    # Chỗ này từng có một ``showEvent`` thứ hai chỉ gọi
+    # ``self._narrow_guard.attach()``. Lớp này còn một ``showEvent`` nữa ở phía
+    # dưới, và Python giữ định nghĩa SAU CÙNG — nên bản ở đây chưa bao giờ chạy.
+    # Đã gộp cả hai việc vào đúng một ``showEvent`` (xem bên dưới).
 
 
 
@@ -309,6 +326,7 @@ class Co4ETab(
         return Path(base) / "co4e"
 
     def _refresh_ws_folder_btn(self) -> None:
+        """Cập nhật nhãn nút thư mục làm việc, rút gọn còn hai cấp cuối cho đỡ dài."""
         root = self._flow_output_root()
         parts = root.parts
         short = "…/" + "/".join(parts[-2:]) if len(parts) > 2 else str(root)
@@ -316,6 +334,7 @@ class Co4ETab(
         self.ws_folder_btn.setToolTip(tr("co4e.tt_open_workspace", path=str(root)))
 
     def _open_workspace_folder(self) -> None:
+        """Mở thư mục kết quả của luồng trong trình quản lý tệp của hệ điều hành."""
         from .osutil import open_location
         root = self._flow_output_root()
         try:
@@ -331,14 +350,26 @@ class Co4ETab(
 
 
     def showEvent(self, e):  # noqa: N802
+        """Mỗi lần tab được hiện lại: làm mới bảng Flow Status và gắn lại bộ canh
+        bố cục hẹp.
+
+        Gắn lại bộ canh là cần: widget có thể đã được chuyển sang cửa sổ khác kể
+        từ lần hiện trước, và bộ canh theo dõi CỬA SỔ chứ không theo dõi widget.
+        """
         # Guarantee the status list is current whenever the tab is shown again.
         self._refresh_runs()
+        self._narrow_guard.attach()
         super().showEvent(e)
 
     def _out_dir(self) -> Path:
         # Save chat/flow deliverables into the SELECTED workspace (the active
         # project's folder via _flow_output_root), so files land where the user
         # works with them — not in the config/install folder.
+        """Thư mục ghi kết quả của luồng đang mở, tạo sẵn nếu chưa có.
+
+        Ghi vào thư mục của workspace đang chọn để file rơi đúng chỗ người dùng làm
+        việc, không rơi vào thư mục cài đặt.
+        """
         d = self._flow_output_root() / co4e.slugify(self._wf.name or "flow")
         d.mkdir(parents=True, exist_ok=True)
         return d
@@ -359,6 +390,7 @@ class Co4ETab(
 
     # ---- i18n -------------------------------------------------------------
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề các mục và tooltip."""
         for key in self._sections:
             self._sync_section_arrow(key)
         self.runs_more_btn.setToolTip(tr("co4e.tt_runs_tab"))
@@ -382,9 +414,13 @@ class Co4ETab(
 
 
 def _html_escape(text: str) -> str:
+    """Thoát ba ký tự HTML nguy hiểm, để nội dung người dùng không phá vỡ khung chat."""
     return (text or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
 
 
 def _qcolor(hex_str: str):
+    """Đổi chuỗi màu hex thành ``QColor``. Import muộn để module này nạp được ở nơi
+    chưa có Qt GUI.
+    """
     from PySide6.QtGui import QColor
     return QColor(hex_str)
diff --git a/ui/composer.py b/ui/composer.py
index 4d717d7..4488bd9 100644
--- a/ui/composer.py
+++ b/ui/composer.py
@@ -1,11 +1,23 @@
 """Vỏ chuyển tiếp — R08-T02.
 
 Phần thân đã chuyển sang ``presentation/chat/composer_widget.py`` (thanh công
-cụ) và ``chat_input_box.py`` (ô nhập).
+cụ), ``chat_input_box.py`` (ô nhập) và ``composer_mime.py`` (đọc dữ liệu
+dán/kéo-thả).
+
+Bốn hàm ``_save_pasted_image``/``_is_local_*_command``/``_paths_from_mime``
+được nối lại dưới đúng tên cũ: chúng là tên riêng tư nên không thuộc API công
+khai, nhưng file này vốn cũng đang chuyển tiếp ``_Input`` và ``_SkillPopup``
+— nối tiếp một nửa thì vỏ chuyển tiếp không còn trung thực với bản gốc.
 """
 from __future__ import annotations
 
 from ..presentation.chat.chat_input_box import _Input, _SkillPopup  # noqa: F401
+from ..presentation.chat.composer_mime import (  # noqa: F401
+    is_local_agent_command as _is_local_agent_command,
+    is_local_skill_command as _is_local_skill_command,
+    paths_from_mime as _paths_from_mime,
+    save_pasted_image as _save_pasted_image,
+)
 from ..presentation.chat.composer_widget import (  # noqa: F401
     Composer,
 )
diff --git a/ui/connectors_panel.py b/ui/connectors_panel.py
index 77f9bd7..457e712 100644
--- a/ui/connectors_panel.py
+++ b/ui/connectors_panel.py
@@ -32,6 +32,7 @@ class JiraConnectDialog(QDialog):
     read and processed automatically (no per-request setup)."""
 
     def __init__(self, ctx: AppContext, parent=None):
+        """Form khai báo kết nối Jira: địa chỉ, tài khoản và token."""
         super().__init__(parent)
         self.ctx = ctx
         self.setWindowTitle(tr("connectors.jira_group"))
@@ -68,12 +69,16 @@ class JiraConnectDialog(QDialog):
         form.addRow(rw)
 
     def _on_paste(self, text: str) -> None:
+        """Dán một link Jira bất kỳ thì tự rút ra base URL — người dùng không phải
+        biết đâu là phần gốc của địa chỉ.
+        """
         from ..core import jira_tool
         base = jira_tool.base_url_from_link(text)
         if base:
             self.url.setText(base)
 
     def _save(self) -> None:
+        """Ghi thông tin Jira vào cấu hình (chưa đóng hộp thoại)."""
         j = self.ctx.config.data.setdefault("jira", {})
         j.update({"base_url": self.url.text().strip(), "email": self.email.text().strip(),
                   "api_token": self.token.text().strip()})
@@ -81,10 +86,12 @@ class JiraConnectDialog(QDialog):
         self.ctx.save()
 
     def _save_close(self) -> None:
+        """Lưu rồi đóng hộp thoại."""
         self._save()
         self.accept()
 
     def _test(self) -> None:
+        """Thử kết nối bằng một truy vấn tối thiểu, chạy ở luồng nền."""
         from ..core import jira_tool
         self._save()
         cfg = self.ctx.config.data.get("jira", {})
@@ -95,9 +102,13 @@ class JiraConnectDialog(QDialog):
         self.test_btn.setEnabled(False)
 
         def job(_w):
+            """Chạy nền: tìm đúng 1 issue mới nhất để xác nhận kết nối sống."""
             return {"out": jira_tool.search(cfg, "order by created DESC", 1)}
 
         def done(r):
+            """Hiện kết quả thử: coi là lỗi khi thông điệp bắt đầu bằng câu báo chưa cấu
+            hình hoặc tìm kiếm thất bại.
+            """
             self.test_btn.setEnabled(True)
             out = r.get("out", "")
             ok = not out.lower().startswith(("jira is not configured", "jira search failed"))
@@ -113,6 +124,11 @@ class JiraConnectDialog(QDialog):
 
 
 class ConnectorsPanel(QWidget):
+    """Bảng Connectors trong Cài đặt: MS365 dựng sẵn, Jira, và connector MCP tự thêm,
+    gom theo bốn nhóm CAD / CAE / MS365 / Khác.
+
+    Có một công tắc tổng: tắt là agent không nối ra connector ngoài nào cả.
+    """
     _EXT_CATEGORY_LABELS = {
         "cad": "CAD (NX / CATIA / SolidWorks / AutoCAD)",
         "cae": "CAE (ANSA / ABAQUS / HyperWorks / ANSYS)",
@@ -126,6 +142,11 @@ class ConnectorsPanel(QWidget):
     _MS365_BUILTIN_LABELS = {"onedrive": "OneDrive", "sharepoint": "SharePoint"}
 
     def __init__(self, ctx: AppContext):
+        """Panel quản lý connector ngoài.
+
+        Công tắc tổng ở trên cùng: tắt là agent KHÔNG nối tới connector nào, bất kể
+        từng connector bên dưới có bật hay không.
+        """
         super().__init__()
         self.ctx = ctx
         lay = QVBoxLayout(self)
@@ -185,6 +206,7 @@ class ConnectorsPanel(QWidget):
 
     # ---- rendering ------------------------------------------------------------
     def _clear_categories(self) -> None:
+        """Xoá sạch các mục nhóm trước khi dựng lại."""
         while self._cat_lay.count():
             item = self._cat_lay.takeAt(0)
             w = item.widget()
@@ -192,11 +214,13 @@ class ConnectorsPanel(QWidget):
                 w.deleteLater()
 
     def _reload_connectors(self) -> None:
+        """Dựng lại toàn bộ bảng từ cấu hình mới nhất."""
         self._clear_categories()
         for cat in EXT_CATEGORIES:
             self._cat_lay.addWidget(self._category_section(cat))
 
     def _category_section(self, cat: str) -> QWidget:
+        """Dựng một mục nhóm kèm lưới thẻ connector bên trong."""
         section = QWidget()
         enable_height_for_width(section)  # this section wraps a FlowLayout row — see FlowLayout
         sl = QVBoxLayout(section)
@@ -260,6 +284,9 @@ class ConnectorsPanel(QWidget):
 
     def _connector_card(self, title: str, subtitle: str, checked: bool, on_toggle,
                         edit_cb=None, delete_cb=None) -> QWidget:
+        """Dựng một thẻ connector: tiêu đề, dòng phụ, công tắc bật/tắt và nút sửa/xoá
+        (nếu có).
+        """
         card = QFrame()
         card.setFrameShape(QFrame.NoFrame)
         style_card(card)
@@ -307,19 +334,23 @@ class ConnectorsPanel(QWidget):
         return card
 
     def _toggle_ms365_builtin(self, key: str, checked: bool) -> None:
+        """Bật/tắt một connector MS365 dựng sẵn và lưu ngay."""
         self.ctx.config.ms365.setdefault("connectors", {})[key] = checked
         self.ctx.save()
 
     def _toggle_jira(self, checked: bool) -> None:
+        """Bật/tắt connector Jira và lưu ngay."""
         self.ctx.config.data.setdefault("jira", {})["enabled"] = checked
         self.ctx.save()
 
     def _toggle_ext_entry(self, entry: dict, checked: bool) -> None:
+        """Bật/tắt một connector MCP tự thêm và lưu ngay."""
         entry["enabled"] = checked
         self.ctx.save()
 
     # ---- CRUD -----------------------------------------------------------------
     def _ext_add(self) -> None:
+        """Thêm một connector MCP mới qua hộp thoại."""
         dlg = ExtConnectorEditDialog(self, category=EXT_CATEGORIES[0])
         if dlg.exec():
             entry = dlg.result_connector()
@@ -328,6 +359,7 @@ class ConnectorsPanel(QWidget):
             self._reload_connectors()
 
     def _edit_ext_entry(self, cat: str, entry: dict) -> None:
+        """Sửa một connector MCP đã có."""
         dlg = ExtConnectorEditDialog(self, category=cat, connector=entry)
         if dlg.exec():
             entry.update(dlg.result_connector())
@@ -335,10 +367,12 @@ class ConnectorsPanel(QWidget):
             self._reload_connectors()
 
     def _open_jira_dialog(self) -> None:
+        """Mở hộp thoại cấu hình Jira rồi dựng lại bảng."""
         JiraConnectDialog(self.ctx, self).exec()
         self._reload_connectors()
 
     def _delete_ext_entry(self, cat: str, entry: dict) -> None:
+        """Xoá một connector MCP sau khi hỏi xác nhận."""
         if QMessageBox.question(
                 self, tr("settings.ext_delete_btn"),
                 tr("settings.ext_delete_confirm", name=entry.get("name", ""))) != QMessageBox.Yes:
@@ -348,6 +382,7 @@ class ConnectorsPanel(QWidget):
         self._reload_connectors()
 
     def _refresh_ms365_local_status(self) -> None:
+        """Cập nhật dòng trạng thái MS365 cục bộ theo việc có tìm thấy thư mục OneDrive hay không."""
         from .. import paths
         root = paths.primary_onedrive_root()
         if root is not None:
@@ -356,6 +391,7 @@ class ConnectorsPanel(QWidget):
             self.ms365_local_status.setText(tr("settings.ms365_local_none"))
 
     def _on_connect_external_toggled(self, on: bool) -> None:
+        """Bật/tắt công tắc tổng cho connector ngoài, và khoá/mở cả bảng theo đó."""
         self.ctx.config.set_connect_external(on)
         self._apply_connect_external_enabled(on)
 
@@ -366,6 +402,7 @@ class ConnectorsPanel(QWidget):
             w.setEnabled(on)
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self.connect_external_sw.setText(tr("connectors.connect_external"))
         self.connect_external_sw.setToolTip(tr("connectors.connect_external_tooltip"))
         self.add_btn.setText(tr("settings.ext_add_btn"))
diff --git a/ui/cowork_tab.py b/ui/cowork_tab.py
index ad47cee..9653cbe 100644
--- a/ui/cowork_tab.py
+++ b/ui/cowork_tab.py
@@ -19,7 +19,15 @@ _FOLDER_LBL_MAX_CHARS = 42  # keep the composer's bottom row from crowding out A
 
 
 class CoworkTab(ChatPanel):
+    """Màn Cowork: khung chat chính, gắn với một project và một thư mục kết quả.
+
+    Khác :class:`ChatPanel` gốc ở chỗ kết quả được gom theo TỪNG hội thoại và
+    chỉ hiện ra sau khi lượt chạy thành công — xem :meth:`register_output`.
+    """
     def __init__(self, ctx: AppContext):
+        """Màn Cowork — một ``ChatPanel`` kèm thanh công cụ riêng hiện provider, model và
+        thư mục kết quả đang dùng.
+        """
         super().__init__(ctx, "cowork", "Cowork", placeholder_key="composer.placeholder_cowork")
 
         self._title_lbl = QLabel()
@@ -95,6 +103,7 @@ class CoworkTab(ChatPanel):
         lbl.setText(getattr(self, "title", "") or tr("cowork.title"))
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề và các nút trên thanh công cụ."""
         self.refresh_title()
         self.skills_btn.setText(tr("cowork.skills_btn"))
         self.skills_btn.setToolTip(tr("cowork.skills_tooltip"))
@@ -105,6 +114,7 @@ class CoworkTab(ChatPanel):
 
     # ---- output folder --------------------------------------------------
     def _pick_output_folder(self) -> None:
+        """Chọn thư mục kết quả cho hội thoại này."""
         start = str(self._session_output_dir())
         chosen = QFileDialog.getExistingDirectory(self, tr("cowork.pick_folder_title"), start)
         if not chosen:
@@ -126,6 +136,11 @@ class CoworkTab(ChatPanel):
         self._refresh_outputs_from_disk()
 
     def _apply_output_folder_label(self) -> None:
+        """Cập nhật nhãn cạnh nút chọn thư mục.
+
+        Chỉ hiện TÊN thư mục; đường dẫn đầy đủ để trong tooltip — bày cả đường dẫn
+        ra ngoài chỉ làm rối một giá trị mà người dùng vừa tự chọn.
+        """
         full = str(self._session_output_dir())
         # Only the folder NAME is shown beside the button — the full path
         # (still available on hover) reads as noisy clutter for a value the
@@ -150,6 +165,7 @@ class CoworkTab(ChatPanel):
 
     # ---- project (workspace) --------------------------------------------
     def _project(self):
+        """Project đang gắn với hội thoại này; ``None`` nếu không tìm thấy."""
         from ..core.projects import load_project
 
         return load_project(self.project_id)
@@ -187,6 +203,7 @@ class CoworkTab(ChatPanel):
                           ".sh", ".bat", ".ps1", ".rb", ".pl"}
 
     def assistant_title(self) -> str:
+        """Nhãn hiện trên bong bóng trả lời của màn Cowork."""
         return tr("cowork.assistant_title")
 
     def _session_output_dir(self):
@@ -222,6 +239,7 @@ class CoworkTab(ChatPanel):
         return self.ctx.config.cowork_output_dir() / self.session_id
 
     def workspace_dir(self):
+        """Thư mục agent được phép đọc/ghi trong hội thoại này."""
         return self._session_output_dir()
 
     def _turn_output_dir(self, turn_id: str):
@@ -234,6 +252,11 @@ class CoworkTab(ChatPanel):
         return self._session_output_dir() / ".turns" / turn_id
 
     def _is_intermediate_output(self, path: str) -> bool:
+        """Tệp này có phải file trung gian (do bước dựng sinh ra) không.
+
+        File trung gian không hiện lên ô "Tệp đầu ra" — người dùng chỉ quan tâm
+        sản phẩm cuối.
+        """
         from pathlib import Path
         return Path(path).suffix.lower() in self._INTERMEDIATE_EXTS
 
@@ -253,6 +276,12 @@ class CoworkTab(ChatPanel):
         # file it made earlier in this same conversation — e.g. "sửa lại tiêu đề
         # trong file báo cáo vừa tạo" — since it can read_file/edit_file/write_file
         # it directly by the exact name listed here.
+        """Ghi chú đính kèm vào prompt: danh sách tệp hội thoại này đã tạo.
+
+        Nhờ đó agent (và người dùng, không phải tải lên lại) tham chiếu và sửa được
+        tệp nó vừa tạo ở lượt trước — ví dụ "sửa lại tiêu đề trong file báo cáo vừa
+        tạo" — vì nó đọc/ghi được tệp đó theo đúng tên liệt kê ở đây.
+        """
         names = self._existing_output_names()
         if not names:
             return ""
@@ -308,9 +337,13 @@ class CoworkTab(ChatPanel):
     def register_output(self, path: str) -> None:
         # Suppress live/intermediate updates during a run — the Output box is
         # rebuilt from the surviving files once the turn succeeds (see below).
+        """Không làm gì: ô "Tệp đầu ra" của Cowork được dựng lại từ các tệp còn sống
+        sau khi lượt chạy THÀNH CÔNG, chứ không cập nhật từng tệp giữa chừng.
+        """
         return
 
     def on_file_written(self, path: str) -> None:
+        """Không làm gì: Cowork không cập nhật danh sách tệp theo thời gian thực."""
         return  # no live file updates in Cowork
 
     def _refresh_outputs_from_disk(self) -> None:
@@ -329,17 +362,22 @@ class CoworkTab(ChatPanel):
 
     def new_session(self) -> None:
         # The new thread stays in the CURRENT project (Claude-style).
+        """Mở hội thoại mới trong ĐÚNG project đang chọn, rồi trỏ lại thư mục kết quả."""
         super().new_session()
         # Refresh the project/folder labels + watch the new session's folder.
         self._apply_output_folder_label()
 
     def load_conversation(self, conv) -> None:
+        """Mở lại một hội thoại cũ: khôi phục project của nó, dựng lại danh sách tệp
+        đầu ra từ đĩa và trỏ lại nhãn thư mục.
+        """
         super().load_conversation(conv)    # restores this conversation's project_id
         self._refresh_outputs_from_disk()  # show this session's deliverables from disk
         # Refresh the project/folder labels + watch this conversation's folder.
         self._apply_output_folder_label()
 
     def refresh_header(self) -> None:
+        """Cập nhật dòng "provider · model" trên thanh công cụ Cowork."""
         cfg = self.ctx.config
         label = PROVIDER_LABELS.get(cfg.active_provider, cfg.active_provider)
         self.model_lbl.setText(f"{label} · {cfg.model_label()}")
@@ -377,6 +415,11 @@ class CoworkTab(ChatPanel):
         model = self._routed_model or self._model or ""
 
         def job(worker: AgentWorker):
+            """Chạy nền một lượt Cowork qua ``ConversationApplicationService`` (R04-T04).
+
+            Sự kiện của service được dịch ngược về khuôn dict cũ để giao diện hiện tại
+            không phải sửa.
+            """
             from ..application.conversations.core_runtime_adapter import (
                 build_cowork_conversation_service,
                 legacy_event_sink,
diff --git a/ui/ext_connector_dialog.py b/ui/ext_connector_dialog.py
index 2244d4a..8c898f4 100644
--- a/ui/ext_connector_dialog.py
+++ b/ui/ext_connector_dialog.py
@@ -26,7 +26,11 @@ _CATEGORY_LABEL = {"cad": "CAD", "cae": "CAE", "other": "Other"}
 
 
 class ExtConnectorEditDialog(QDialog):
+    """Hộp thoại thêm/sửa một connector ngoài: MCP server hoặc REST API."""
     def __init__(self, parent=None, category: str = "cad", connector: Optional[dict] = None):
+        """Form thêm/sửa một connector ngoài. ``connector`` để None thì đây là form thêm
+        mới; nhóm (CAD/CAE/MS365/Other) lấy từ connector cũ nếu đang sửa.
+        """
         super().__init__(parent)
         connector = connector or {}
         self.category = connector.get("category", category)
@@ -121,6 +125,11 @@ class ExtConnectorEditDialog(QDialog):
         lay.addWidget(buttons)
 
     def _reload_presets(self) -> None:
+        """Nạp lại danh sách mẫu dựng sẵn theo nhóm đang chọn.
+
+        Chặn tín hiệu trong lúc nạp: ``clear()`` phát ``currentIndexChanged`` và sẽ
+        bị hiểu nhầm là người dùng vừa chọn mẫu.
+        """
         self.preset_combo.blockSignals(True)
         self.preset_combo.clear()
         self.preset_combo.addItem(tr("ext.preset_custom"), "")
@@ -129,15 +138,18 @@ class ExtConnectorEditDialog(QDialog):
         self.preset_combo.blockSignals(False)
 
     def _on_category_changed(self) -> None:
+        """Đổi nhóm (CAD/CAE/MS365/Khác) thì nạp lại danh sách mẫu tương ứng."""
         self.category = self.category_combo.currentData() or self.category
         self._reload_presets()
 
     def _apply_preset(self) -> None:
+        """Áp một mẫu dựng sẵn; chỉ điền tên khi người dùng chưa tự đặt tên."""
         preset_id = self.preset_combo.currentData()
         if preset_id and not self.name_edit.text().strip():
             self.name_edit.setText(self.preset_combo.currentText())
 
     def _current_entry(self) -> dict:
+        """Bản ghi connector dựng từ nội dung đang có trên form."""
         mode = self.mode_combo.currentData()
         preset_id = self.preset_combo.currentData()
         name = self.name_edit.text().strip()
@@ -159,6 +171,7 @@ class ExtConnectorEditDialog(QDialog):
         }
 
     def _test_connection(self) -> None:
+        """Thử kết nối tới connector đang cấu hình và hiện kết quả."""
         entry = self._current_entry()
         if entry["mode"] == "rest_api":
             from ..core.ext_connectors import RestApiConnector
@@ -182,6 +195,7 @@ class ExtConnectorEditDialog(QDialog):
         self.status_label.setText(f"{prefix} {message}")
 
     def _on_accept(self) -> None:
+        """Kiểm tra bắt buộc có tên trước khi đóng hộp thoại."""
         if not self.name_edit.text().strip():
             self.name_edit.setFocus()
             return
@@ -195,4 +209,5 @@ class ExtConnectorEditDialog(QDialog):
         self.accept()
 
     def result_connector(self) -> dict:
+        """Bản ghi connector để chỗ gọi lưu lại."""
         return self._current_entry()
diff --git a/ui/file_edit_dialog.py b/ui/file_edit_dialog.py
index 792259f..5465e1a 100644
--- a/ui/file_edit_dialog.py
+++ b/ui/file_edit_dialog.py
@@ -51,6 +51,11 @@ class FileEditDialog(QDialog):
     """Pick/view a file and apply AI edits to it (see module docstring)."""
 
     def __init__(self, ctx=None, path: str = "", parent=None):
+        """Hộp thoại xem/sửa một tệp.
+
+        Mở ở chế độ CHỈ ĐỌC; muốn sửa phải bật rõ ràng, và lần ghi đầu tiên tự sao
+        lưu bản gốc.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._worker: Optional[AgentWorker] = None
@@ -121,11 +126,13 @@ class FileEditDialog(QDialog):
 
     # ---- loading -----------------------------------------------------------
     def _browse(self) -> None:
+        """Chọn tệp cần sửa."""
         path, _ = QFileDialog.getOpenFileName(self, tr("fileedit.title"))
         if path:
             self.load_file(path)
 
     def _reload(self) -> None:
+        """Đọc lại tệp đang mở từ đĩa, bỏ mọi sửa đổi chưa lưu."""
         if self.path_edit.text():
             self.load_file(self.path_edit.text())
 
@@ -167,6 +174,7 @@ class FileEditDialog(QDialog):
                                 + (f" ({note})" if note else ""))
 
     def _set_editable(self, editable: bool) -> None:
+        """Bật/tắt chế độ sửa được (tệp nhị phân hoặc chỉ đọc thì tắt)."""
         self._editable = editable
         self.editor.setReadOnly(not editable)
         self.save_btn.setEnabled(editable)
@@ -175,6 +183,7 @@ class FileEditDialog(QDialog):
 
     # ---- AI edit -------------------------------------------------------------
     def _ai_edit(self) -> None:
+        """Nhờ AI sửa tệp theo yêu cầu; thiếu yêu cầu hoặc đang chạy dở thì bỏ qua."""
         instruction = self.instruction_edit.text().strip()
         if (not instruction or not self._editable or self.ctx is None
                 or self._worker is not None):
@@ -188,6 +197,7 @@ class FileEditDialog(QDialog):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi model sửa nội dung tệp theo yêu cầu."""
             provider = ctx.build_active_provider()
             messages = [
                 {"role": "system", "content": _SYSTEM_PROMPT},
@@ -199,6 +209,10 @@ class FileEditDialog(QDialog):
             return {"text": (a.get("content") or "").strip()}
 
         def done(result: dict) -> None:
+            """Đổ nội dung đã sửa vào ô soạn thảo, bỏ hàng rào code của model.
+
+            KHÔNG tự ghi đĩa: người dùng phải bấm Lưu.
+            """
             self._worker = None
             self.ai_btn.setEnabled(True)
             new_text = _strip_fences(result.get("text", ""))
@@ -209,6 +223,7 @@ class FileEditDialog(QDialog):
                 self.status_lbl.setText(tr("fileedit.ai_empty"))
 
         def failed(err: str) -> None:
+            """Sửa lỗi: hiện lý do (cắt ở 300 ký tự) và mở khoá lại nút."""
             self._worker = None
             self.ai_btn.setEnabled(True)
             self.status_lbl.setText(tr("fileedit.ai_failed", err=err[:300]))
@@ -221,6 +236,7 @@ class FileEditDialog(QDialog):
 
     # ---- save -----------------------------------------------------------------
     def _save(self) -> None:
+        """Ghi nội dung đang sửa xuống tệp."""
         path = self.path_edit.text()
         if not path or not self._editable:
             return
diff --git a/ui/flow_dialog.py b/ui/flow_dialog.py
index d7edcf8..45a42f1 100644
--- a/ui/flow_dialog.py
+++ b/ui/flow_dialog.py
@@ -32,7 +32,16 @@ from .skill_manager_tab import SkillManagerTab
 
 
 class FlowBuilderDialog(QDialog):
+    """Trình dựng luồng cũ: danh sách bước bên trái, form sửa bước bên phải.
+
+    Đã được Co4E Studio thay thế và không còn nơi nào mở nó ra; giữ lại làm bản
+    đối chiếu cho phần luồng nhiều bước.
+
+    Một luồng là danh sách ``FlowStep`` chạy tuần tự; mỗi bước có thể chọn
+    riêng skill, provider, model, tệp đính kèm và các sub-agent chạy kèm.
+    """
     def __init__(self, parent=None, ctx=None):
+        """Dựng hộp thoại và nạp sẵn luồng mẫu để người dùng có cái mà sửa ngay."""
         super().__init__(parent)
         self.setWindowTitle(tr("flow.title"))
         self.setMinimumSize(820, 560)
@@ -263,6 +272,10 @@ class FlowBuilderDialog(QDialog):
 
     # ---- AI: generate task prompt from the hint ---------------------
     def _gen_prompt(self) -> None:
+        """Nhờ model viết nội dung bước từ tên bước và câu gợi ý ngắn.
+
+        Không có ``ctx`` (mở hộp thoại ngoài ứng dụng) thì nút này không làm gì.
+        """
         hint = self.step_hint.text().strip()
         name = self.step_name.text().strip()
         if not hint and not name:
@@ -275,6 +288,7 @@ class FlowBuilderDialog(QDialog):
         ctx = self._ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi model sinh nội dung cho bước."""
             from ..core.flows import generate_task_prompt
             return {"prompt": generate_task_prompt(
                 ctx.build_active_provider(), name, hint, worker.is_cancelled)}
@@ -286,23 +300,27 @@ class FlowBuilderDialog(QDialog):
         w.start()
 
     def _on_gen_prompt(self, result) -> None:
+        """Đổ nội dung model vừa sinh vào ô soạn, rồi trả nút về trạng thái thường."""
         text = (result or {}).get("prompt", "")
         if text:
             self.step_prompt.setPlainText(text)
         self._reset_gen_prompt_btn()
 
     def _reset_gen_prompt_btn(self) -> None:
+        """Bật lại nút sinh nội dung và trả chữ về như cũ."""
         self._gen_prompt_btn.setEnabled(True)
         self._gen_prompt_btn.setText(tr("flow.gen_task_from_hint"))
 
     # ---- attachments (per stage) -------------------------------------
     def _pick_attachments(self) -> None:
+        """Chọn tệp đính kèm cho bước đang sửa."""
         chosen, _ = QFileDialog.getOpenFileNames(self, tr("flow.attach_files"))
         if chosen:
             self._step_attachments = chosen
             self._refresh_attach_btn()
 
     def _refresh_attach_btn(self) -> None:
+        """Cập nhật nhãn nút đính kèm theo số tệp; tooltip liệt kê đủ đường dẫn."""
         n = len(self._step_attachments)
         label = tr("flow.attach_files_count", n=n) if n else tr("flow.attach_files")
         self.attach_btn.setText(label)
@@ -312,6 +330,7 @@ class FlowBuilderDialog(QDialog):
     # ``self._step_subagents`` is the source of truth; ``subagents_list`` is
     # just its display — avoids any lossy re-parsing of the list widget text.
     def _add_subagent(self) -> None:
+        """Thêm một sub-agent tự nhập (tên + nội dung) vào bước đang sửa."""
         name = self.sub_name_edit.text().strip()
         if not name:
             self.sub_name_edit.setFocus()
@@ -323,12 +342,14 @@ class FlowBuilderDialog(QDialog):
         self._refresh_subagents_list()
 
     def _remove_subagent(self) -> None:
+        """Gỡ sub-agent đang chọn khỏi bước."""
         row = self.subagents_list.currentRow()
         if 0 <= row < len(self._step_subagents):
             self._step_subagents.pop(row)
             self._refresh_subagents_list()
 
     def _refresh_subagents_list(self) -> None:
+        """Vẽ lại danh sách sub-agent của bước đang sửa."""
         self.subagents_list.clear()
         for sub in self._step_subagents:
             text = f"{sub.name}: {sub.prompt}" if sub.prompt else sub.name
@@ -336,6 +357,9 @@ class FlowBuilderDialog(QDialog):
 
     # ---- add a sub-agent from a saved custom Agent preset -------------
     def _reload_agent_picker(self) -> None:
+        """Nạp danh sách agent tự tạo vào bộ chọn; chưa có agent nào thì khoá bộ chọn
+        lại kèm dòng giải thích, thay vì để một ô rỗng bấm được mà không ra gì.
+        """
         self.agent_picker.clear()
         agents = list_agents()
         if not agents:
@@ -347,6 +371,9 @@ class FlowBuilderDialog(QDialog):
             self.agent_picker.addItem(a.name, a)
 
     def _add_subagent_from_agent(self) -> None:
+        """Thêm sub-agent bằng cách lấy nguyên một agent tự tạo (kèm provider và model
+        riêng của nó).
+        """
         agent = self.agent_picker.currentData()
         if agent is None:
             return
@@ -371,6 +398,7 @@ class FlowBuilderDialog(QDialog):
         self.step_skill.blockSignals(False)
 
     def _populate_combos(self) -> None:
+        """Nạp các bộ chọn của form bước: skill, provider và model."""
         self._reload_skill_combo()
         self.step_agent.blockSignals(True)
         self.step_agent.clear()
@@ -395,6 +423,9 @@ class FlowBuilderDialog(QDialog):
             self.step_model.setCurrentIndex(1)
 
         def job(worker: AgentWorker):
+            """Chạy nền: hỏi provider danh sách model. Lỗi thì trả danh sách rỗng — danh
+            sách model chỉ là tiện ích, không đáng làm vỡ hộp thoại.
+            """
             try:
                 provider = self._ctx.build_provider_for(provider_key)
                 return {"models": provider.list_models() or [], "provider": provider_key}
@@ -402,6 +433,11 @@ class FlowBuilderDialog(QDialog):
                 return {"models": [], "provider": provider_key}
 
         def done(result: dict) -> None:
+            """Đổ danh sách model vào bộ chọn.
+
+            Kết quả về mà provider đã bị đổi lần nữa thì bỏ — nếu không, danh sách của
+            provider cũ sẽ đè lên provider người dùng vừa chọn.
+            """
             if result.get("provider") != (self.step_agent.currentData()
                                           or self._ctx.config.active_provider):
                 return   # provider changed again while fetching — stale reply
@@ -425,6 +461,7 @@ class FlowBuilderDialog(QDialog):
         w.start()
 
     def _reload_templates(self) -> None:
+        """Nạp lại bộ chọn luồng đã lưu."""
         self.tpl_combo.blockSignals(True)
         self.tpl_combo.clear()
         self.tpl_combo.addItem(tr("flow.select_template"), None)
@@ -433,20 +470,28 @@ class FlowBuilderDialog(QDialog):
         self.tpl_combo.blockSignals(False)
 
     def _load_selected_template(self, _idx: int) -> None:
+        """Mở luồng vừa chọn trong bộ chọn.
+
+        Nạp một BẢN SAO SÂU: người dùng sửa rồi bỏ ngang thì luồng đã lưu vẫn
+        nguyên vẹn.
+        """
         flow = self.tpl_combo.currentData()
         if isinstance(flow, Flow):
             self._loaded_name = flow.name
             self._bind_flow(copy.deepcopy(flow))
 
     def _load_builtin(self) -> None:
+        """Nạp lại luồng mẫu dựng sẵn."""
         self._loaded_name = ""
         self._bind_flow(default_req_to_demo())
 
     def _new_flow(self) -> None:
+        """Bắt đầu một luồng trống mới."""
         self._loaded_name = ""
         self._bind_flow(Flow(name=tr("flow.new_flow_name"), description="", steps=[]))
 
     def _delete_template(self) -> None:
+        """Xoá luồng đang chọn khỏi danh sách đã lưu."""
         flow = self.tpl_combo.currentData()
         if isinstance(flow, Flow):
             delete_flow(flow.name)
@@ -454,6 +499,7 @@ class FlowBuilderDialog(QDialog):
 
     # ---- flow <-> widgets -------------------------------------------
     def _bind_flow(self, flow: Flow) -> None:
+        """Đổ một luồng vào toàn bộ giao diện và chọn sẵn bước đầu tiên."""
         self._flow = flow
         self.name_edit.setText(flow.name)
         self.desc_edit.setText(flow.description)
@@ -464,6 +510,7 @@ class FlowBuilderDialog(QDialog):
             self._clear_editor()
 
     def _refresh_steps(self) -> None:
+        """Vẽ lại danh sách bước, mỗi dòng kèm nhãn skill/provider/model của bước đó."""
         self.steps_list.blockSignals(True)
         self.steps_list.clear()
         for i, step in enumerate(self._flow.steps, 1):
@@ -485,6 +532,7 @@ class FlowBuilderDialog(QDialog):
         self.steps_list.blockSignals(False)
 
     def _clear_editor(self) -> None:
+        """Xoá trắng form sửa bước."""
         self.step_name.clear()
         self.step_prompt.clear()
         self.step_hint.clear()
@@ -501,6 +549,12 @@ class FlowBuilderDialog(QDialog):
         self._refresh_subagents_list()
 
     def _load_step_into_editor(self, row: int) -> None:
+        """Đổ một bước vào form sửa.
+
+        Model được nhớ riêng vào ``_pending_step_model`` vì danh sách model nạp bất
+        đồng bộ — không giữ lại thì lựa chọn của người dùng biến mất khi danh sách
+        về tới nơi.
+        """
         if not (0 <= row < len(self._flow.steps)):
             return
         step = self._flow.steps[row]
@@ -522,6 +576,9 @@ class FlowBuilderDialog(QDialog):
         self._refresh_subagents_list()
 
     def _editor_step(self) -> Optional[FlowStep]:
+        """Dựng ``FlowStep`` từ nội dung form; ``None`` nếu chưa nhập tên bước (con trỏ
+        nhảy vào ô tên thay vì hiện hộp lỗi).
+        """
         name = self.step_name.text().strip()
         if not name:
             self.step_name.setFocus()
@@ -541,6 +598,7 @@ class FlowBuilderDialog(QDialog):
         )
 
     def _add_step(self) -> None:
+        """Thêm bước đang soạn vào cuối luồng và chọn nó."""
         step = self._editor_step()
         if step:
             self._flow.steps.append(step)
@@ -548,6 +606,7 @@ class FlowBuilderDialog(QDialog):
             self.steps_list.setCurrentRow(len(self._flow.steps) - 1)
 
     def _update_step(self) -> None:
+        """Ghi đè bước đang chọn bằng nội dung form."""
         row = self.steps_list.currentRow()
         step = self._editor_step()
         if step and 0 <= row < len(self._flow.steps):
@@ -556,12 +615,16 @@ class FlowBuilderDialog(QDialog):
             self.steps_list.setCurrentRow(row)
 
     def _remove_step(self) -> None:
+        """Xoá bước đang chọn khỏi luồng."""
         row = self.steps_list.currentRow()
         if 0 <= row < len(self._flow.steps):
             self._flow.steps.pop(row)
             self._refresh_steps()
 
     def _move(self, delta: int) -> None:
+        """Đổi chỗ bước đang chọn lên/xuống một vị trí — thứ tự bước chính là thứ tự
+        chạy.
+        """
         row = self.steps_list.currentRow()
         new = row + delta
         if 0 <= row < len(self._flow.steps) and 0 <= new < len(self._flow.steps):
@@ -572,11 +635,15 @@ class FlowBuilderDialog(QDialog):
 
     # ---- result -----------------------------------------------------
     def _collect(self) -> Flow:
+        """Lấy tên và mô tả từ form vào luồng rồi trả về nó. Tên bỏ trống thì dùng tên
+        mặc định, không để luồng không tên.
+        """
         self._flow.name = self.name_edit.text().strip() or tr("flow.default_name")
         self._flow.description = self.desc_edit.text().strip()
         return self._flow
 
     def _save_template(self) -> None:
+        """Lưu luồng hiện tại. Truyền ``old_name`` để đổi tên không sinh ra bản thứ hai."""
         flow = self._collect()
         save_flow(flow, old_name=self._loaded_name)
         self._loaded_name = flow.name
@@ -586,6 +653,9 @@ class FlowBuilderDialog(QDialog):
             self.tpl_combo.setCurrentIndex(idx)
 
     def _run(self) -> None:
+        """Đóng hộp thoại kèm yêu cầu chạy luồng. Luồng chưa có bước nào thì không làm
+        gì.
+        """
         flow = self._collect()
         if not flow.steps:
             return
@@ -593,4 +663,5 @@ class FlowBuilderDialog(QDialog):
         self.accept()
 
     def result_flow(self) -> Flow:
+        """Luồng cuối cùng bên gọi nhận về sau khi hộp thoại đóng."""
         return self._collect()
diff --git a/ui/help_agent_widget.py b/ui/help_agent_widget.py
index 29c85a1..423367b 100644
--- a/ui/help_agent_widget.py
+++ b/ui/help_agent_widget.py
@@ -61,6 +61,7 @@ _HIDDEN, _LAUNCHER_ST, _PANEL = "hidden", "launcher", "panel"
 
 
 def _current_user() -> str:
+    """Tên đăng nhập hệ điều hành, dùng để chào người dùng; '' nếu không đọc được."""
     return (os.environ.get("USERNAME") or os.environ.get("USER") or "").strip()
 
 
@@ -84,11 +85,13 @@ class _HoverPill(QPushButton):
     """
 
     def __init__(self, owner):
+        """Nút tròn nổi ở góc màn hình, mở ra panel Trợ giúp khi bấm."""
         super().__init__(owner)
         self._owner = owner
         self.open = False
 
     def _set_open(self, value: bool) -> None:
+        """Đổi trạng thái bung/co và vẽ lại; đã đúng trạng thái thì bỏ qua."""
         if value == self.open:
             return
         self.open = value
@@ -96,19 +99,23 @@ class _HoverPill(QPushButton):
         self._owner._layout_launcher()
 
     def enterEvent(self, e):  # noqa: N802 - Qt override
+        """Rê chuột vào: bung ra."""
         self._set_open(True)
         super().enterEvent(e)
 
     def leaveEvent(self, e):  # noqa: N802 - Qt override
+        """Rời chuột: co lại — trừ khi đang giữ focus bàn phím."""
         if not self.hasFocus():
             self._set_open(False)
         super().leaveEvent(e)
 
     def focusInEvent(self, e):  # noqa: N802 - Qt override
+        """Nhận focus bàn phím: bung ra, để người dùng dùng Tab cũng thấy được nhãn."""
         self._set_open(True)
         super().focusInEvent(e)
 
     def focusOutEvent(self, e):  # noqa: N802 - Qt override
+        """Mất focus: co lại."""
         self._set_open(False)
         super().focusOutEvent(e)
 
@@ -120,6 +127,11 @@ class HelpAgentWidget(QWidget):
     status_message = Signal(str)
 
     def __init__(self, ctx, parent=None, user_name: str = ""):
+        """Trợ lý Trợ giúp trong ứng dụng.
+
+        Giữ lịch sử hội thoại riêng (không kèm prompt hệ thống — cái đó ghép vào ở
+        mỗi lượt gọi) để người dùng hỏi tiếp mà không phải nhắc lại bối cảnh.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self._user_name = user_name or _current_user()
@@ -204,6 +216,7 @@ class HelpAgentWidget(QWidget):
 
     # ---- greeting / labels ------------------------------------------------
     def _greeting(self) -> str:
+        """Câu chào mở đầu, có tên người dùng nếu biết."""
         name = self._user_name or tr("help_agent.default_user")
         return tr("help_agent.greeting", name=name)
 
@@ -211,6 +224,7 @@ class HelpAgentWidget(QWidget):
     def _build_edge_tab(self) -> None:
         # Shown only while hidden: a thin tab at the right edge to bring the
         # assistant back (chevron points left = "slide out").
+        """Dựng thẻ mỏng ở mép phải — chỉ hiện khi trợ lý đang ẩn hẳn, bấm vào để gọi lại."""
         self.edge_tab = QPushButton(self)
         self.edge_tab.setObjectName("helpEdgeTab")
         self.edge_tab.setIcon(icon("chevron-left", color=_TEAL_TEXT))
@@ -222,6 +236,12 @@ class HelpAgentWidget(QWidget):
         # One control, one job: this opens the chat. The chevron that used to sit
         # beside it (a second 18px hit target for a second meaning of "closed")
         # is gone — hiding to the edge is now a line in the panel's ⋯ menu.
+        """Dựng nút mở chat.
+
+        Một nút, một việc: mở khung chat. Cái chevron từng đứng cạnh nó (thêm một
+        vùng bấm 18px cho một nghĩa "đóng" thứ hai) đã bỏ — muốn ẩn hẳn thì vào
+        menu ⋯ của panel.
+        """
         self.launcher = _HoverPill(self)
         self.launcher.setObjectName("helpLauncher")
         self.launcher.setIcon(icon("sparkle", size=_DOT_ICON, color=_SPARK_GOLD))
@@ -231,6 +251,7 @@ class HelpAgentWidget(QWidget):
         self.launcher.clicked.connect(self._expand)
 
     def _build_panel(self) -> None:
+        """Dựng panel chat: dòng thời gian, ô nhập, nút gửi và menu ⋯."""
         self.panel = QFrame(self)
         self.panel.setObjectName("helpPanel")
 
@@ -301,11 +322,13 @@ class HelpAgentWidget(QWidget):
 
     # ---- state transitions ------------------------------------------------
     def _expand(self) -> None:
+        """Mở panel chat đầy đủ và đưa con trỏ vào ô nhập."""
         self._state = _PANEL
         self._apply_state()
         self.input.setFocus()
 
     def _collapse(self) -> None:
+        """Thu panel về nút tròn."""
         self._state = _LAUNCHER_ST
         self._apply_state()
 
@@ -323,10 +346,12 @@ class HelpAgentWidget(QWidget):
         menu.exec(widget.mapToGlobal(pos))
 
     def _hide_to_edge(self) -> None:
+        """Ẩn hẳn trợ lý, chỉ chừa thẻ mỏng ở mép phải."""
         self._state = _HIDDEN
         self._apply_state()
 
     def _show_launcher(self) -> None:
+        """Gọi trợ lý trở lại từ trạng thái ẩn."""
         self._state = _LAUNCHER_ST
         self._apply_state()
 
@@ -346,6 +371,7 @@ class HelpAgentWidget(QWidget):
         self.raise_()
 
     def _apply_state(self) -> None:
+        """Áp trạng thái hiện tại lên ba thành phần: thẻ mép, nút tròn và panel."""
         st = self._state
         self.edge_tab.setVisible(st == _HIDDEN)
         self.launcher.setVisible(st == _LAUNCHER_ST)
@@ -412,6 +438,10 @@ class HelpAgentWidget(QWidget):
         )
 
     def _render(self, pending: bool = False) -> None:
+        """Dựng lại toàn bộ dòng thời gian dưới dạng HTML.
+
+        ``pending=True`` thêm một bong bóng "…" để báo đang chờ trả lời.
+        """
         parts = [self._bubble_html(m["role"], m["content"]) for m in self._history]
         if pending:
             parts.append(self._bubble_html("assistant", "…"))
@@ -420,6 +450,7 @@ class HelpAgentWidget(QWidget):
 
     # ---- send a message ---------------------------------------------------
     def _send(self) -> None:
+        """Gửi câu hỏi tới Help Agent ở luồng nền."""
         if self._busy:
             return
         text = self.input.text().strip()
@@ -435,6 +466,7 @@ class HelpAgentWidget(QWidget):
         history = list(self._history)
 
         def job(worker):
+            """Chạy nền: gọi provider của Help Agent kèm prompt hệ thống của nó."""
             provider = admin_agents.build_agent_provider(self.ctx, agent)
             messages = [{"role": "system", "content": agent.effective_prompt()}] + history
             result = provider.chat(messages, tools=None, cancel=worker.is_cancelled)
@@ -448,18 +480,21 @@ class HelpAgentWidget(QWidget):
         worker.start()
 
     def _on_reply(self, result: Dict[str, Any]) -> None:
+        """Nhận trả lời và vẽ vào dòng thời gian; rỗng thì hiện câu thay thế."""
         content = (result or {}).get("content", "").strip() or tr("help_agent.empty_reply")
         self._history.append({"role": "assistant", "content": content})
         self._set_busy(False)
         self._render()
 
     def _on_failed(self, err: str) -> None:
+        """Gọi lỗi: hiện thông báo lỗi ngay trong khung chat thay vì im lặng."""
         self._history.append({"role": "assistant",
                               "content": tr("help_agent.error", error=err)})
         self._set_busy(False)
         self._render()
 
     def _set_busy(self, busy: bool) -> None:
+        """Khoá/mở ô nhập và nút gửi trong lúc chờ trả lời."""
         self._busy = busy
         self.input.setEnabled(not busy)
         self.send_btn.setEnabled(not busy)
@@ -468,6 +503,12 @@ class HelpAgentWidget(QWidget):
         # The transcript is rendered HTML, so switching language left the
         # greeting — and every "AI Assistant" speaker label — in the language
         # the panel was built in.
+        """Áp lại chữ theo ngôn ngữ đang chọn.
+
+        Dòng thời gian là HTML đã dựng sẵn, nên đổi ngôn ngữ mà không dựng lại sẽ
+        để câu chào — và mọi nhãn người nói "AI Assistant" — nằm nguyên ở ngôn ngữ
+        lúc panel được tạo.
+        """
         if self._history and self._history[0] is self._greet_msg:
             self._greet_msg["content"] = self._greeting()
         self._render()
diff --git a/ui/icons.py b/ui/icons.py
index a91160c..dca22d5 100644
--- a/ui/icons.py
+++ b/ui/icons.py
@@ -351,6 +351,7 @@ class IconLabel(QWidget):
 
     def __init__(self, name: str, text: str = "", *, size: int = 16,
                  color: str | None = None, gap: int = 6, parent=None):
+        """Một nhãn có biểu tượng đứng trước chữ, dùng cho các hàng thông tin."""
         super().__init__(parent)
         self._size = size
         lay = QHBoxLayout(self)
@@ -364,12 +365,17 @@ class IconLabel(QWidget):
         lay.addStretch(1)
 
     def set_text(self, text: str) -> None:
+        """Đổi phần chữ của nhãn."""
         self._text.setText(text)
 
     def setText(self, text: str) -> None:  # noqa: N802 — QLabel-compatible alias
+        """Bí danh hợp chuẩn ``QLabel`` của :meth:`set_text`, để thay thế trực tiếp
+        cho một ``QLabel`` mà không phải sửa chỗ gọi.
+        """
         self._text.setText(text)
 
     def set_icon(self, name: str, color: str | None = None) -> None:
+        """Đổi icon (và màu icon) của nhãn."""
         self._icon.setPixmap(pixmap(name, self._size, color))
 
     def text_label(self) -> QLabel:
diff --git a/ui/icons_admin_tab.py b/ui/icons_admin_tab.py
index 6e43a2d..62418df 100644
--- a/ui/icons_admin_tab.py
+++ b/ui/icons_admin_tab.py
@@ -21,6 +21,7 @@ from .icons import icon
 
 
 def _grid() -> QListWidget:
+    """Dựng lưới hiển thị icon dạng ô vuông có nhãn."""
     g = QListWidget()
     g.setObjectName("iconGrid")   # accent border on hover/selection, see theme.py
     g.setViewMode(QListWidget.IconMode)
@@ -33,7 +34,13 @@ def _grid() -> QListWidget:
 
 
 class IconsAdminTab(QWidget):
+    """Tab "Icon" trong màn Giám sát: xem bộ icon hệ thống và thay icon bằng ảnh riêng."""
     def __init__(self, ctx: AppContext):
+        """Tab quản trị biểu tượng: bộ dựng sẵn và bộ tự thêm.
+
+        Ba nút thao tác nằm cạnh tiêu đề chứ không nằm dưới hai lưới — đặt dưới thì
+        chúng trông như chỉ áp cho lưới tự thêm.
+        """
         super().__init__()
         self.ctx = ctx
         root = QVBoxLayout(self)
@@ -81,6 +88,7 @@ class IconsAdminTab(QWidget):
 
     # ---- rendering --------------------------------------------------------
     def _reload_builtin(self, *_a) -> None:
+        """Nạp lại lưới icon dựng sẵn, lọc theo ô tìm kiếm."""
         q = self.search.text().strip().lower()
         self.builtin_grid.clear()
         for name in sorted(icons_mod._PATHS):
@@ -92,6 +100,7 @@ class IconsAdminTab(QWidget):
             self.builtin_grid.addItem(it)
 
     def _reload_custom(self) -> None:
+        """Nạp lại lưới icon do người dùng thêm."""
         self.custom_grid.clear()
         for name in custom_icons.list_custom():
             it = QListWidgetItem(icon(name), name)
@@ -102,6 +111,7 @@ class IconsAdminTab(QWidget):
 
     # ---- actions ----------------------------------------------------------
     def _add_icon(self) -> None:
+        """Thêm icon mới từ một tệp SVG."""
         from PySide6.QtWidgets import QFileDialog
         path, _ = QFileDialog.getOpenFileName(self, tr("icons_admin.add"), "", "SVG (*.svg)")
         if not path:
@@ -118,6 +128,7 @@ class IconsAdminTab(QWidget):
         self._reload_custom()
 
     def _add_from_svg_text(self) -> None:
+        """Thêm icon bằng cách dán thẳng mã SVG."""
         name, ok = QInputDialog.getText(self, tr("icons_admin.name_prompt"),
                                         tr("icons_admin.name_prompt"))
         if not ok or not name.strip():
@@ -134,6 +145,7 @@ class IconsAdminTab(QWidget):
         self._reload_custom()
 
     def _delete_icon(self) -> None:
+        """Xoá icon tự thêm đang chọn; chưa chọn gì thì nhắc người dùng."""
         item = self.custom_grid.currentItem()
         if item is None:
             QMessageBox.information(self, tr("icons_admin.title"), tr("icons_admin.select_custom"))
@@ -142,6 +154,7 @@ class IconsAdminTab(QWidget):
         self._reload_custom()
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._title.setText(tr("monitoring.tab_icons"))
         self._hint.setText(tr("icons_admin.hint"))
         self.search.setPlaceholderText(tr("icons_admin.search"))
diff --git a/ui/libreoffice_view.py b/ui/libreoffice_view.py
index 9d747a0..938390d 100644
--- a/ui/libreoffice_view.py
+++ b/ui/libreoffice_view.py
@@ -37,6 +37,7 @@ DOC_SUFFIXES = {
 
 
 def is_document(path) -> bool:
+    """Đuôi tệp này có phải tài liệu LibreOffice mở được không."""
     return Path(path).suffix.lower() in DOC_SUFFIXES
 
 
@@ -74,6 +75,11 @@ class LibreOfficeView(QWidget):
     MAX_TRIES = 40  # ~16s to find the window before giving up
 
     def __init__(self):
+        """Khung nhúng cửa sổ LibreOffice vào trong ứng dụng.
+
+        Chưa chạy tiến trình nào; hồ sơ riêng và cửa sổ được dựng ở lần mở tệp đầu
+        tiên.
+        """
         super().__init__()
         self._proc: subprocess.Popen | None = None
         self._profile_dir: Path | None = None
@@ -108,10 +114,12 @@ class LibreOfficeView(QWidget):
         on_language_changed(self._retranslate)
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._open_btn.setText(tr("libreoffice.open_btn"))
 
     # ---- public API --------------------------------------------------
     def open_document(self, path: str) -> None:
+        """Mở một tài liệu: đóng cái đang mở, khởi động soffice rồi nhúng cửa sổ của nó."""
         self.close_document()
         self._path = str(path)
         soffice = find_soffice()
@@ -124,6 +132,7 @@ class LibreOfficeView(QWidget):
         self._launch_and_embed(soffice)
 
     def close_document(self) -> None:
+        """Đóng tài liệu: dừng bộ đếm dò, gỡ cửa sổ nhúng và tắt tiến trình soffice."""
         self._poll.stop()
         self._tries = 0
         if self._container is not None:
@@ -141,6 +150,12 @@ class LibreOfficeView(QWidget):
 
     # ---- launch + embed (Windows) ------------------------------------
     def _launch_and_embed(self, soffice: str) -> None:
+        """Khởi động soffice với một profile RIÊNG rồi bắt đầu dò cửa sổ của nó.
+
+        Profile riêng trong thư mục tạm là bắt buộc: dùng chung profile mặc định thì
+        instance thứ hai sẽ nối vào instance đang chạy của người dùng và không có
+        cửa sổ mới nào để nhúng.
+        """
         try:
             self._profile_dir = Path(tempfile.mkdtemp(prefix=f"lo-embed-{uuid.uuid4().hex[:8]}-"))
             profile_url = "file:///" + str(self._profile_dir).replace("\\", "/")
@@ -160,6 +175,11 @@ class LibreOfficeView(QWidget):
         self._poll.start()
 
     def _try_embed(self) -> None:
+        """Một nhịp dò: tìm cửa sổ soffice và nhúng, quá ``MAX_TRIES`` thì bỏ cuộc.
+
+        Phải dò theo nhịp vì soffice tạo cửa sổ sau khi tiến trình đã khởi động —
+        không có tín hiệu nào báo "cửa sổ đã sẵn sàng".
+        """
         self._tries += 1
         if self._tries > self.MAX_TRIES:
             self._poll.stop()
@@ -183,6 +203,7 @@ class LibreOfficeView(QWidget):
 
         @ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
         def _cb(hwnd, _lparam):
+            """Callback duyệt cửa sổ của Windows: nhận cửa sổ đang hiện và đúng lớp của soffice."""
             if not user32.IsWindowVisible(hwnd):
                 return True
             cls = ctypes.create_unicode_buffer(256)
@@ -204,6 +225,7 @@ class LibreOfficeView(QWidget):
         return found[0] if found else None
 
     def _embed_hwnd(self, hwnd: int) -> None:
+        """Đổi cha của cửa sổ soffice sang widget này và bỏ khung viền của nó."""
         try:
             user32 = _win_user32()
             GWL_STYLE = -16
@@ -229,6 +251,11 @@ class LibreOfficeView(QWidget):
 
     # ---- cleanup -----------------------------------------------------
     def _post_close(self, hwnd: int) -> None:
+        """Gửi lệnh đóng tới cửa sổ soffice đang nhúng.
+
+        Đóng lịch sự thay vì giết tiến trình, để LibreOffice kịp dọn file khoá — bỏ
+        qua bước này thì lần mở sau nó báo tài liệu đang bị dùng.
+        """
         try:
             WM_CLOSE = 0x0010
             _win_user32().PostMessageW(hwnd, WM_CLOSE, 0, 0)
@@ -236,6 +263,11 @@ class LibreOfficeView(QWidget):
             pass
 
     def _cleanup_proc(self, graceful: bool = True) -> None:
+        """Dọn tiến trình soffice và thư mục profile tạm của nó.
+
+        ``graceful=True`` đóng lịch sự trước rồi mới giết; profile tạm luôn bị xoá,
+        nếu không mỗi lần mở tài liệu lại để lại một thư mục rác.
+        """
         proc, self._proc = self._proc, None
         profile, self._profile_dir = self._profile_dir, None
         if proc is not None and proc.poll() is None:
@@ -252,6 +284,9 @@ class LibreOfficeView(QWidget):
             shutil.rmtree(profile, ignore_errors=True)
 
     def _open_external(self) -> None:
+        """Mở tài liệu bằng ứng dụng mặc định của hệ điều hành — lối thoát khi không
+        nhúng được cửa sổ.
+        """
         if not self._path:
             return
         soffice = find_soffice()
@@ -265,10 +300,14 @@ class LibreOfficeView(QWidget):
 
     # ---- small helpers -----------------------------------------------
     def _show_message(self, text: str, offer_open: bool = False) -> None:
+        """Hiện một dòng thông báo thay cho khung xem, kèm nút mở bằng ứng dụng ngoài
+        nếu có.
+        """
         self._info.setText(text)
         self._info.setVisible(True)
         self._open_btn.setVisible(bool(offer_open and self._path))
 
     def _clear_info(self) -> None:
+        """Ẩn dòng thông báo và nút mở ngoài."""
         self._info.setVisible(False)
         self._open_btn.setVisible(False)
diff --git a/ui/login_dialog.py b/ui/login_dialog.py
index 1956ef7..4dcef95 100644
--- a/ui/login_dialog.py
+++ b/ui/login_dialog.py
@@ -39,11 +39,18 @@ class _AccountEdit(QLineEdit):
     """Account field: alnum/./- only, auto-lowercased as the user types."""
 
     def __init__(self):
+        """Ô nhập tên tài khoản, tự chuẩn hoá theo từng ký tự gõ vào."""
         super().__init__()
         self.setMaxLength(64)
         self.textChanged.connect(self._normalize)
 
     def _normalize(self, text: str) -> None:
+        """Ép về chữ thường và chỉ giữ chữ–số–dấu chấm–gạch.
+
+        Tên tài khoản thành tên file trên thư mục dùng chung, nên khoảng trắng và ký
+        tự lạ phải chặn ngay tại ô nhập chứ không đợi tới lúc lưu. Vị trí con trỏ
+        được đặt lại sau khi sửa chữ, nếu không nó nhảy về cuối sau mỗi ký tự.
+        """
         cleaned = re.sub(r"[^\w.\-]", "", text.lower())
         if cleaned == text:
             return
@@ -55,7 +62,18 @@ class _AccountEdit(QLineEdit):
 
 
 class LoginDialog(QDialog):
+    """Hộp thoại đăng nhập, ba trang tuỳ tình trạng thư mục dùng chung.
+
+    * Chưa cấu hình thư mục, hoặc có mà chưa có tài khoản nào — trang khởi tạo,
+      nơi người đầu tiên nhận suất Admin.
+    * Thư mục tới được — trang đăng nhập bằng tên tài khoản và mã.
+    * Thư mục không tới được — trang ngoại tuyến, cho vào bằng lần đăng nhập
+      gần nhất đã nhớ, để mất mạng không đồng nghĩa với mất luôn ứng dụng.
+
+    Bản đang chạy không có lớp đăng nhập nên hộp thoại này không được mở ra.
+    """
     def __init__(self, ctx: AppContext, parent=None):
+        """Chọn và dựng đúng một trong ba trang theo tình trạng thư mục dùng chung."""
         super().__init__(parent)
         self.ctx = ctx
         self.account: Optional[Account] = None
@@ -91,6 +109,11 @@ class LoginDialog(QDialog):
     # ---- helpers -----------------------------------------------------
     @staticmethod
     def _is_reachable(shared_dir: str) -> bool:
+        """Thư mục dùng chung có tới được không (ổ mạng có thể rớt bất cứ lúc nào).
+
+        Mọi ``OSError`` đều tính là không tới được: đường dẫn sai, hết quyền hay ổ
+        mạng rớt đều dẫn tới cùng một lối đi ngoại tuyến.
+        """
         if not shared_dir:
             return False
         try:
@@ -99,6 +122,12 @@ class LoginDialog(QDialog):
             return False
 
     def _finish_login(self, account: Account) -> None:
+        """Ghi nhận đăng nhập thành công rồi đóng hộp thoại.
+
+        Mã được cất vào keyring để lần sau khỏi gõ lại — nhưng chỉ khi có mã thật:
+        lối vào ngoại tuyến không có mã, cất chuỗi rỗng vào sẽ hỏng lần đăng nhập
+        tự động sau đó.
+        """
         self.account = account
         accounts.save_last_login(account.username, account.role)
         self.ctx.config.auth["last_account"] = account.username
@@ -114,6 +143,7 @@ class LoginDialog(QDialog):
 
     # ---- bootstrap (no shared folder / no accounts yet) ---------------
     def _build_bootstrap_page(self) -> QWidget:
+        """Trang khởi tạo: chọn thư mục dùng chung và tạo tài khoản Admin đầu tiên."""
         page = QWidget()
         lay = QVBoxLayout(page)
         lay.addWidget(QLabel(tr("login.bootstrap_hint")))
@@ -141,11 +171,18 @@ class LoginDialog(QDialog):
         return page
 
     def _bs_browse(self) -> None:
+        """Mở hộp thoại chọn thư mục dùng chung."""
         chosen = QFileDialog.getExistingDirectory(self, tr("login.shared_dir"))
         if chosen:
             self.bs_dir_edit.setText(chosen)
 
     def _bs_create_admin(self) -> None:
+        """Tạo tài khoản Admin đầu tiên.
+
+        Suất Admin được giành bằng ``claim_admin_slot`` chứ không chỉ kiểm tra rồi
+        ghi: hai máy cùng khởi tạo trên một thư mục dùng chung sẽ chỉ có một máy
+        thắng, thay vì cả hai cùng thành Admin.
+        """
         shared_dir = self.bs_dir_edit.text().strip()
         username = self.bs_user_edit.text().strip()
         if not shared_dir or not username:
@@ -175,6 +212,7 @@ class LoginDialog(QDialog):
 
     # ---- normal login ---------------------------------------------------
     def _build_login_page(self, shared_dir: str) -> QWidget:
+        """Trang đăng nhập thường: tên tài khoản + mã, điền sẵn tài khoản lần trước."""
         page = QWidget()
         lay = QVBoxLayout(page)
         form = QFormLayout()
@@ -214,6 +252,9 @@ class LoginDialog(QDialog):
         return page
 
     def _do_login(self, shared_dir: str) -> None:
+        """Kiểm tra tên tài khoản và mã; sai thì báo ngay trên trang, không đóng hộp
+        thoại.
+        """
         username = self.user_edit.text().strip()
         code = self.code_edit.text().strip()
         directory = accounts.accounts_dir(shared_dir)
@@ -246,6 +287,9 @@ class LoginDialog(QDialog):
 
     # ---- offline fallback (shared folder configured but unreachable) ----
     def _build_offline_page(self, shared_dir: str) -> QWidget:
+        """Trang ngoại tuyến: cho vào bằng vai trò của lần đăng nhập gần nhất, kèm nút
+        thử lại.
+        """
         page = QWidget()
         lay = QVBoxLayout(page)
         lay.addWidget(QLabel(tr("login.unreachable", path=shared_dir)))
@@ -266,6 +310,7 @@ class LoginDialog(QDialog):
         return page
 
     def _retry(self) -> None:
+        """Kiểm tra lại thư mục dùng chung và dựng lại trang cho đúng tình trạng mới."""
         self._stack.removeWidget(self._stack.currentWidget())
         shared_dir = self.ctx.config.shared_dir
         reachable = self._is_reachable(shared_dir)
diff --git a/ui/mcp_servers_dialog.py b/ui/mcp_servers_dialog.py
index d64b868..1050422 100644
--- a/ui/mcp_servers_dialog.py
+++ b/ui/mcp_servers_dialog.py
@@ -13,7 +13,12 @@ from ..i18n import tr
 
 
 class McpServerEditDialog(QDialog):
+    """Form thêm/sửa một máy chủ MCP: tên, lệnh chạy, tham số và công tắc bật.
+
+    Đã được ``ui/connectors_panel.py`` thay thế; giữ lại làm bản đối chiếu.
+    """
     def __init__(self, parent=None, server: Optional[dict] = None):
+        """Dựng form. ``server`` để None thì đây là form thêm mới."""
         super().__init__(parent)
         server = server or {}
         self.setWindowTitle(tr("mcp.edit_title") if server else tr("mcp.add_title"))
@@ -42,12 +47,20 @@ class McpServerEditDialog(QDialog):
         lay.addWidget(buttons)
 
     def _on_accept(self) -> None:
+        """Chỉ đóng khi đã có tên và lệnh chạy — thiếu một trong hai thì máy chủ không
+        khởi động được. Con trỏ nhảy về ô tên thay vì hiện hộp lỗi.
+        """
         if not self.name.text().strip() or not self.command.text().strip():
             self.name.setFocus()
             return
         self.accept()
 
     def result_server(self) -> dict:
+        """Nội dung form dưới dạng dict.
+
+        Tham số được tách bằng ``shlex`` chứ không phải ``split()``: đường dẫn có
+        khoảng trắng phải đặt trong dấu nháy và vẫn tính là MỘT tham số.
+        """
         args_text = self.args.text().strip()
         return {
             "name": self.name.text().strip(),
diff --git a/ui/osutil.py b/ui/osutil.py
index 8bde730..adda9fa 100644
--- a/ui/osutil.py
+++ b/ui/osutil.py
@@ -12,6 +12,7 @@ _URL_RE = re.compile(r"^https?://", re.IGNORECASE)
 
 
 def is_image(path: str | Path) -> bool:
+    """Đuôi tệp này có phải ảnh không."""
     return Path(path).suffix.lower() in IMAGE_SUFFIXES
 
 
diff --git a/ui/permission_dialog.py b/ui/permission_dialog.py
index fcea9e0..63a7891 100644
--- a/ui/permission_dialog.py
+++ b/ui/permission_dialog.py
@@ -11,7 +11,15 @@ from ..i18n import tr
 
 
 class PermissionDialog(QDialog):
+    """Hộp thoại xin phép chạy một tool có rủi ro: hiện xem trước hành động rồi hỏi
+    Đồng ý / Từ chối.
+    """
     def __init__(self, action: Dict[str, Any], parent=None):
+        """Hộp thoại xin phép trước khi agent chạy một hành động nhạy cảm.
+
+        Hiện nguyên văn thứ sắp chạy: người dùng phải thấy đúng cái mình đang đồng ý,
+        không phải một câu mô tả chung chung.
+        """
         super().__init__(parent)
         preview = action.get("preview", {})
         self.setWindowTitle(tr("permission.title"))
diff --git a/ui/routing_toggle.py b/ui/routing_toggle.py
index 0ffc26d..d235a55 100644
--- a/ui/routing_toggle.py
+++ b/ui/routing_toggle.py
@@ -51,6 +51,11 @@ class RoutingToggle(QWidget):
         get_mode: Optional[Callable[[], str]] = None,
         set_mode: Optional[Callable[[str], None]] = None,
     ) -> None:
+        """Công tắc chế độ định tuyến cho một bề mặt chat.
+
+        ``get_mode``/``set_mode`` tiêm được để dùng lại công tắc này ở chỗ đọc/ghi
+        chế độ theo cách khác, mà không phải chép lại cả widget.
+        """
         super().__init__(parent)
         self.ctx = ctx
         self.surface = surface
@@ -85,6 +90,7 @@ class RoutingToggle(QWidget):
         lay.addWidget(self._combo)
 
     def current_mode(self) -> str:
+        """Chế độ định tuyến đang chọn; 'off' nếu chưa đặt."""
         return self._combo.currentData() or "off"
 
     def refresh(self) -> None:
@@ -109,6 +115,9 @@ class RoutingToggle(QWidget):
             self._combo.setItemText(i, tr(key))
 
     def _on_changed(self, _idx: int) -> None:
+        """Lưu chế độ vừa chọn. Nuốt lỗi có chủ ý: một cú đổi công tắc không được
+        phép làm vỡ giao diện.
+        """
         mode = self.current_mode()
         try:
             self._set_mode(mode)
@@ -129,6 +138,7 @@ class AutoRunToggle(QWidget):
     toggled_auto = Signal(bool)
 
     def __init__(self, ctx: Any, parent: Optional[QWidget] = None) -> None:
+        """Ô tick tự chạy: đổi model xong có tự tiếp tục lượt hay dừng lại hỏi."""
         super().__init__(parent)
         self.ctx = ctx
         lay = QHBoxLayout(self)
@@ -141,6 +151,7 @@ class AutoRunToggle(QWidget):
         lay.addWidget(self._chk)
 
     def refresh(self) -> None:
+        """Đọc lại trạng thái tự chạy của project đang mở lên ô đánh dấu."""
         try:
             auto = bool(self.ctx.project_auto_run())
         except Exception:  # noqa: BLE001
@@ -150,10 +161,12 @@ class AutoRunToggle(QWidget):
         self._chk.blockSignals(False)
 
     def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._chk.setText(tr("routing.autorun_label"))
         self._chk.setToolTip(tr("routing.autorun_tooltip"))
 
     def _on_toggled(self, checked: bool) -> None:
+        """Ghi trạng thái tự chạy vào project đang mở."""
         try:
             self.ctx.set_project_auto_run(bool(checked))
         except Exception:  # noqa: BLE001
@@ -194,6 +207,11 @@ def confirm_switch(parent: QWidget, decision: Any, timeout_sec: float) -> bool:
     timer.setInterval(1000)
 
     def _tick() -> None:
+        """Đếm lùi mỗi giây; hết giờ thì tự đóng hộp thoại theo hướng GIỮ model hiện tại.
+
+        Hết giờ mà tự đổi model là quyết định thay người dùng — mặc định an toàn
+        phải là không đổi gì.
+        """
         remaining["secs"] -= 1
         if remaining["secs"] <= 0:
             timer.stop()
diff --git a/ui/settings_dialog.py b/ui/settings_dialog.py
index 338b926..823f14c 100644
--- a/ui/settings_dialog.py
+++ b/ui/settings_dialog.py
@@ -33,7 +33,15 @@ from ..presentation.settings.parameter_settings_widget import ParameterSettingsW
 from ..presentation.settings.routing_settings_widget import RoutingSettingsWidget
 
 class SettingsDialog(QDialog):
+    """Hộp thoại Cài đặt: cột mục lục bên trái, các trang bên phải
+    (Nhà cung cấp · Connectors · Định tuyến · Tham số · Chung).
+    """
     def __init__(self, ctx, parent=None):
+        """Hộp thoại Cài đặt, ghép các nhóm thiết lập.
+
+        Có nút thu nhỏ (không phải mặc định của hộp thoại Qt) vì màn này hay được để
+        mở trong lúc người dùng làm việc ở cửa sổ chính.
+        """
         super().__init__()
         self.ctx = ctx
         self.setWindowTitle(tr("settings.title"))
@@ -241,6 +249,7 @@ class SettingsDialog(QDialog):
 
     @staticmethod
     def _group(title: str, rows) -> QGroupBox:
+        """Dựng một nhóm có tiêu đề chứa các hàng nhãn–điều khiển."""
         box = QGroupBox(title)
         form = QFormLayout(box)
         for label, widget in rows:
@@ -261,6 +270,11 @@ class SettingsDialog(QDialog):
 
 
     def _sandbox_unlock(self) -> None:
+        """Mở khoá nhóm cài đặt sandbox bằng mật khẩu.
+
+        Đây là khoá phía giao diện để chặn bấm nhầm vào một mục nhạy cảm, KHÔNG
+        phải cơ chế bảo mật thật.
+        """
         pw = self.sandbox_pw_edit.text()
         if pw == self._sandbox_pw:
             self._sandbox_unlocked = True
@@ -275,6 +289,7 @@ class SettingsDialog(QDialog):
             QMessageBox.warning(self, "Wrong Password", "Password incorrect. Sandbox settings remain locked.")
 
     def _save(self) -> None:
+        """Gom cấu hình từ mọi trang con rồi ghi xuống đĩa."""
         data = self.ctx.config.data
         self._provider_page.apply_to(data)
         self._general_box.apply_to(data)
diff --git a/ui/sidebar.py b/ui/sidebar.py
index 4c04f72..4675903 100644
--- a/ui/sidebar.py
+++ b/ui/sidebar.py
@@ -26,6 +26,10 @@ class _SessionDelegate(QStyledItemDelegate):
     look."""
 
     def paint(self, painter, option, index):  # noqa: N802
+        """Vẽ một dòng hội thoại: tiêu đề, chấm trạng thái và nền của dòng đang mở.
+
+        Dòng tiêu đề nhóm (không mang dữ liệu hội thoại) để Qt vẽ mặc định.
+        """
         if not index.data(Qt.UserRole):       # group header → default
             super().paint(painter, option, index)
             return
@@ -58,6 +62,7 @@ class _SessionDelegate(QStyledItemDelegate):
         style.drawControl(QStyle.CE_ItemViewItem, opt, painter, widget)
 
     def sizeHint(self, option, index):  # noqa: N802
+        """Dòng hội thoại cao hơn dòng nhóm 16px để có chỗ cho dòng phụ."""
         size = super().sizeHint(option, index)
         if index.data(Qt.UserRole):
             size.setHeight(size.height() + 16)
@@ -65,6 +70,10 @@ class _SessionDelegate(QStyledItemDelegate):
 
 
 class HistorySidebar(QWidget):
+    """Cột lịch sử hội thoại: tìm kiếm, gom nhóm theo project, ghim, xoá hàng loạt.
+
+    Gập lại được thành một dải mỏng để nhường chỗ cho khung chat.
+    """
     new_chat = Signal(str)          # kind
     open_chat = Signal(str, dict)   # kind, conversation
     collapse_requested = Signal()   # in-header button: collapse to a strip
@@ -73,6 +82,11 @@ class HistorySidebar(QWidget):
     history_changed = Signal()      # a conversation was deleted — other views (Project tab) should re-sync
 
     def __init__(self, ctx: AppContext):
+        """Cột lịch sử hội thoại.
+
+        Nhúng trong tab Cowork của một dự án thì chỉ hiện hội thoại của dự án ấy;
+        ``_project_filter`` rỗng nghĩa là hiện tất cả, gom theo dự án.
+        """
         super().__init__()
         self.ctx = ctx
         self.current_session_id = ""     # conversation currently on screen (highlighted)
@@ -155,6 +169,7 @@ class HistorySidebar(QWidget):
         on_language_changed(self._retranslate)
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, ô tìm và các tooltip."""
         self._strip.setToolTip(tr("sidebar.expand_tooltip"))
         self._collapse_btn.setToolTip(tr("sidebar.collapse_tooltip"))
         self._header.setText(tr("sidebar.header"))
@@ -165,6 +180,7 @@ class HistorySidebar(QWidget):
         self.refresh()   # re-render group headers / running suffix in the new language
 
     def is_collapsed(self) -> bool:
+        """Cột đang ở trạng thái gập (chỉ còn dải mỏng) hay không."""
         return self._strip.isVisible()
 
     def set_collapsed(self, collapsed: bool) -> None:
@@ -200,6 +216,7 @@ class HistorySidebar(QWidget):
         query = self.search_box.text() if hasattr(self, "search_box") else ""
 
         def _make_group(label: str) -> QTreeWidgetItem:
+            """Dựng một dòng tiêu đề nhóm (theo project) trong cây lịch sử."""
             node = QTreeWidgetItem([label])
             node.setIcon(0, icon("folder"))
             node.setFirstColumnSpanned(True)
@@ -271,6 +288,11 @@ class HistorySidebar(QWidget):
         # Shift/Ctrl-click means "extend the multi-selection", not "open this
         # conversation" — otherwise every click while multi-selecting for a
         # bulk-delete would also jump into that conversation.
+        """Bấm một dòng: mở hội thoại đó.
+
+        Giữ Shift/Ctrl thì KHÔNG mở — lúc đó người dùng đang chọn nhiều dòng để
+        xoá hàng loạt, mở hội thoại giữa chừng sẽ phá thao tác đang làm.
+        """
         if QApplication.keyboardModifiers() & (Qt.ShiftModifier | Qt.ControlModifier):
             return
         path = item.data(0, Qt.UserRole)
@@ -281,6 +303,7 @@ class HistorySidebar(QWidget):
         self.open_chat.emit(kind, conv)
 
     def _selected_conversation_items(self):
+        """Các dòng đang chọn thật sự là hội thoại (bỏ qua dòng tiêu đề nhóm)."""
         return [it for it in self.tree.selectedItems() if it.data(0, Qt.UserRole)]
 
     @staticmethod
@@ -291,6 +314,7 @@ class HistorySidebar(QWidget):
         return len(selected) > 1 and item in selected
 
     def _context_menu(self, pos) -> None:
+        """Menu chuột phải: đổi tên, ghim, mở thư mục, xoá — hỗ trợ chọn nhiều dòng."""
         clicked = self.tree.itemAt(pos)
         if clicked is None:
             return
diff --git a/ui/skill_manager_tab.py b/ui/skill_manager_tab.py
index 9181c9e..1b8c3e3 100644
--- a/ui/skill_manager_tab.py
+++ b/ui/skill_manager_tab.py
@@ -27,7 +27,13 @@ from .skills_dialog import SkillEditDialog
 
 
 class SkillManagerTab(QWidget):
+    """Màn quản lý skill cũ: danh sách có ô tick bật/tắt, kèm nút nhập/xuất/nhân
+    bản và hai lối nhờ model tự sinh skill.
+
+    Đã được ``ui/skills_dialog.py`` thay thế; giữ lại làm bản đối chiếu.
+    """
     def __init__(self, ctx=None, parent=None):
+        """Dựng danh sách skill và hàng nút thao tác."""
         super().__init__(parent)
         self._ctx = ctx
         self._auto_worker: Optional[AgentWorker] = None
@@ -85,6 +91,11 @@ class SkillManagerTab(QWidget):
 
     # ---- AI: auto-generate a whole skill from a one-line description ----
     def _auto_generate(self) -> None:
+        """Nhờ model viết một skill mới từ mô tả người dùng gõ vào.
+
+        Không có ``ctx`` (mở tab ngoài ứng dụng) thì báo là chưa dùng được, chứ
+        không im lặng.
+        """
         if self._ctx is None:
             QMessageBox.information(self, tr("skills.auto_generate_title"),
                                     tr("skills.auto_generate_unavailable"))
@@ -100,6 +111,9 @@ class SkillManagerTab(QWidget):
         text = prompt.strip()
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi model sinh skill. Lỗi được gói vào kết quả thay vì ném ra, để
+            luồng gọi lại luôn chạy tới nơi.
+            """
             try:
                 skill = generate_skill(ctx.build_active_provider(), text, worker.is_cancelled)
                 return {"skill": skill}
@@ -113,6 +127,7 @@ class SkillManagerTab(QWidget):
         w.start()
 
     def _on_auto_generated(self, result) -> None:
+        """Mở form sửa với skill model vừa sinh, để người dùng xem lại trước khi lưu."""
         self._auto_btn.setEnabled(True)
         self._auto_btn.setText(tr("skills.auto_generate"))
         skill = (result or {}).get("skill")
@@ -127,6 +142,7 @@ class SkillManagerTab(QWidget):
 
     # ---- AI: analyze a pptx/xlsx TEMPLATE file's structure into a skill ----
     def _from_template(self) -> None:
+        """Nhờ model dựng skill từ một file mẫu người dùng chọn."""
         if self._ctx is None:
             QMessageBox.information(self, tr("skills.from_template_title"),
                                     tr("skills.auto_generate_unavailable"))
@@ -141,6 +157,7 @@ class SkillManagerTab(QWidget):
         ctx = self._ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: đọc file mẫu và nhờ model dựng skill từ đó."""
             try:
                 skill = generate_skill_from_template(
                     ctx.build_active_provider(), path, worker.is_cancelled)
@@ -155,6 +172,7 @@ class SkillManagerTab(QWidget):
         w.start()
 
     def _on_template_generated(self, result) -> None:
+        """Mở form sửa với skill dựng từ file mẫu."""
         self._template_btn.setEnabled(True)
         self._template_btn.setText(tr("skills.from_template"))
         skill = (result or {}).get("skill")
@@ -168,6 +186,7 @@ class SkillManagerTab(QWidget):
             self.reload()
 
     def reload(self) -> None:
+        """Nạp lại danh sách skill từ đĩa, giữ đúng trạng thái bật/tắt của từng cái."""
         self.list.blockSignals(True)
         self.list.clear()
         for s in list_skills():
@@ -184,6 +203,7 @@ class SkillManagerTab(QWidget):
         self.list.blockSignals(False)
 
     def _on_check(self, item: QListWidgetItem) -> None:
+        """Tick/bỏ tick một skill là bật/tắt nó, ghi đĩa ngay."""
         skill = item.data(Qt.UserRole)
         if not isinstance(skill, Skill):
             return
@@ -191,6 +211,7 @@ class SkillManagerTab(QWidget):
         save_skill(skill)
 
     def _current_skill(self) -> Optional[Skill]:
+        """Skill đang chọn; ``None`` nếu chưa chọn dòng nào."""
         item = self.list.currentItem()
         if item is None:
             return None
@@ -198,6 +219,7 @@ class SkillManagerTab(QWidget):
         return skill if isinstance(skill, Skill) else None
 
     def _import(self) -> None:
+        """Nhập một skill từ file ngoài vào."""
         from ..core.skills import import_skill_file
 
         path, _ = QFileDialog.getOpenFileName(
@@ -211,6 +233,7 @@ class SkillManagerTab(QWidget):
             QMessageBox.warning(self, tr("skills.import_dialog_title"), tr("skills.import_failed", err=exc))
 
     def _export_md(self) -> None:
+        """Xuất skill đang chọn ra file Markdown."""
         skill = self._current_skill()
         if skill is None:
             QMessageBox.information(self, tr("skills.export_btn"), tr("skills.export_pick"))
@@ -229,6 +252,11 @@ class SkillManagerTab(QWidget):
             QMessageBox.warning(self, tr("skills.export_btn"), tr("skills.export_failed", err=exc))
 
     def _duplicate(self) -> None:
+        """Nhân bản skill đang chọn.
+
+        Bản sao được tạo ở trạng thái TẮT rồi mở form sửa ngay: nhân bản là để lấy
+        làm nền sửa tiếp, chưa phải để chạy.
+        """
         skill = self._current_skill()
         if skill is None:
             QMessageBox.information(self, tr("skills.duplicate_btn"), tr("skills.export_pick"))
@@ -243,6 +271,9 @@ class SkillManagerTab(QWidget):
             self.reload()
 
     def _edit(self) -> None:
+        """Mở form sửa skill đang chọn. Truyền ``old_name`` để đổi tên không sinh ra
+        bản thứ hai.
+        """
         skill = self._current_skill()
         if skill is None:
             return
@@ -252,6 +283,7 @@ class SkillManagerTab(QWidget):
             self.reload()
 
     def _delete(self) -> None:
+        """Xoá skill đang chọn."""
         skill = self._current_skill()
         if skill is None:
             return
diff --git a/ui/skills_dialog.py b/ui/skills_dialog.py
index 2530859..3dbe4b5 100644
--- a/ui/skills_dialog.py
+++ b/ui/skills_dialog.py
@@ -21,7 +21,13 @@ from .icons import icon
 
 
 class SkillEditDialog(QDialog):
+    """Hộp thoại thêm/sửa một Skill: tên, mô tả và phần chỉ dẫn."""
     def __init__(self, parent=None, skill: Optional[Skill] = None, ctx=None):
+        """Form thêm/sửa một skill.
+
+        Skill mới luôn bắt đầu ở trạng thái TẮT: vừa tạo xong đã tự tham gia vào mọi
+        lượt chat là điều người dùng không lường trước.
+        """
         super().__init__(parent)
         self.setWindowTitle(tr("skills.edit_title") if skill else tr("skills.add_title"))
         self.setMinimumWidth(520)
@@ -59,6 +65,7 @@ class SkillEditDialog(QDialog):
 
     # ---- AI: draft the instructions from the short description -------
     def _gen_instructions(self) -> None:
+        """Nhờ AI soạn phần chỉ dẫn từ tên và mô tả người dùng vừa gõ."""
         desc = self.desc.text().strip()
         name = self.name.text().strip()
         if not desc and not name:
@@ -71,6 +78,7 @@ class SkillEditDialog(QDialog):
         ctx = self._ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi model sinh nội dung chỉ dẫn cho skill."""
             return {"text": generate_skill_instructions(
                 ctx.build_active_provider(), desc, name, worker.is_cancelled)}
 
@@ -81,22 +89,26 @@ class SkillEditDialog(QDialog):
         w.start()
 
     def _on_gen(self, result) -> None:
+        """Đổ chỉ dẫn vừa sinh vào ô soạn thảo."""
         text = (result or {}).get("text", "")
         if text:
             self.instr.setPlainText(text)
         self._reset_gen_btn()
 
     def _reset_gen_btn(self) -> None:
+        """Trả nút "Sinh từ mô tả" về trạng thái bấm được."""
         self._gen_btn.setEnabled(True)
         self._gen_btn.setText(tr("skills.gen_from_desc"))
 
     def _on_accept(self) -> None:
+        """Kiểm tra bắt buộc có tên trước khi đóng hộp thoại."""
         if not self.name.text().strip():
             self.name.setFocus()
             return
         self.accept()
 
     def result_skill(self) -> Skill:
+        """Bản ghi Skill dựng từ nội dung đang có trên form."""
         return Skill(
             name=self.name.text().strip(),
             description=self.desc.text().strip(),
@@ -106,7 +118,13 @@ class SkillEditDialog(QDialog):
 
 
 class SkillsDialog(QDialog):
+    """Trình quản lý Skill: liệt kê, bật/tắt, thêm/sửa/xoá, nhân bản, nhập/xuất,
+    và hai lối tạo nhanh bằng AI (từ mô tả, hoặc từ một tệp mẫu).
+    """
     def __init__(self, parent=None, ctx=None):
+        """Hộp thoại quản lý skill: danh sách kèm nút nhập/xuất và hai lối nhờ model tự
+        sinh skill.
+        """
         super().__init__(parent)
         self._ctx = ctx   # passed to SkillEditDialog for AI-assisted generation
         self._auto_worker = None
@@ -169,6 +187,7 @@ class SkillsDialog(QDialog):
 
     # ---- AI: auto-generate a whole skill from a one-line description ----
     def _auto_generate(self) -> None:
+        """Nhờ AI dựng một skill hoàn chỉnh từ vài dòng mô tả người dùng gõ."""
         if self._ctx is None:
             QMessageBox.information(self, tr("skills.auto_generate_title"),
                                     tr("skills.auto_generate_unavailable"))
@@ -184,6 +203,7 @@ class SkillsDialog(QDialog):
         text = prompt.strip()
 
         def job(worker: AgentWorker):
+            """Chạy nền: gọi model sinh skill; lỗi thì trả về kèm thông điệp để hiện ra."""
             try:
                 skill = generate_skill(ctx.build_active_provider(), text, worker.is_cancelled)
                 return {"skill": skill}
@@ -197,6 +217,7 @@ class SkillsDialog(QDialog):
         w.start()
 
     def _on_auto_generated(self, result) -> None:
+        """Skill vừa sinh xong: mở hộp thoại sửa để người dùng xem lại trước khi lưu."""
         self._auto_btn.setEnabled(True)
         self._auto_btn.setText(tr("skills.auto_generate"))
         skill = (result or {}).get("skill")
@@ -212,6 +233,7 @@ class SkillsDialog(QDialog):
 
     # ---- AI: analyze a pptx/xlsx TEMPLATE file's structure into a skill ----
     def _from_template(self) -> None:
+        """Nhờ AI dựng skill từ một tệp mẫu người dùng chọn (quy trình, biểu mẫu…)."""
         if self._ctx is None:
             QMessageBox.information(self, tr("skills.from_template_title"),
                                     tr("skills.auto_generate_unavailable"))
@@ -226,6 +248,7 @@ class SkillsDialog(QDialog):
         ctx = self._ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: đọc tệp mẫu và gọi model sinh skill tương ứng."""
             try:
                 skill = generate_skill_from_template(
                     ctx.build_active_provider(), path, worker.is_cancelled)
@@ -240,6 +263,7 @@ class SkillsDialog(QDialog):
         w.start()
 
     def _on_template_generated(self, result) -> None:
+        """Skill từ mẫu đã sinh xong: mở hộp thoại sửa để xem lại trước khi lưu."""
         self._template_btn.setEnabled(True)
         self._template_btn.setText(tr("skills.from_template"))
         skill = (result or {}).get("skill")
@@ -253,6 +277,11 @@ class SkillsDialog(QDialog):
             self._reload()
 
     def _reload(self) -> None:
+        """Nạp lại danh sách skill.
+
+        Chặn tín hiệu trong lúc nạp: đặt lại ô đánh dấu sẽ phát ``itemChanged`` và bị
+        hiểu nhầm là người dùng vừa bật/tắt skill.
+        """
         self.list.blockSignals(True)
         self.list.clear()
         for s in list_skills():
@@ -269,6 +298,7 @@ class SkillsDialog(QDialog):
         self.list.blockSignals(False)
 
     def _on_check(self, item: QListWidgetItem) -> None:
+        """Bật/tắt một skill và lưu ngay."""
         skill = item.data(Qt.UserRole)
         if not isinstance(skill, Skill):
             return
@@ -276,6 +306,7 @@ class SkillsDialog(QDialog):
         save_skill(skill)
 
     def _current_skill(self) -> Optional[Skill]:
+        """Skill đang chọn trong danh sách; ``None`` nếu chưa chọn gì."""
         item = self.list.currentItem()
         if item is None:
             return None
@@ -283,6 +314,7 @@ class SkillsDialog(QDialog):
         return skill if isinstance(skill, Skill) else None
 
     def _import(self) -> None:
+        """Nhập skill từ tệp ``.md`` hoặc gói ``.zip``."""
         from ..core.skills import import_skill_file
 
         path, _ = QFileDialog.getOpenFileName(
@@ -296,6 +328,7 @@ class SkillsDialog(QDialog):
             QMessageBox.warning(self, tr("skills.import_dialog_title"), tr("skills.import_failed", err=exc))
 
     def _export_md(self) -> None:
+        """Xuất skill đang chọn ra tệp Markdown."""
         skill = self._current_skill()
         if skill is None:
             QMessageBox.information(self, tr("skills.export_btn"), tr("skills.export_pick"))
@@ -313,6 +346,7 @@ class SkillsDialog(QDialog):
             QMessageBox.warning(self, tr("skills.export_btn"), tr("skills.export_failed", err=exc))
 
     def _duplicate(self) -> None:
+        """Nhân bản skill đang chọn thành một skill mới."""
         skill = self._current_skill()
         if skill is None:
             QMessageBox.information(self, tr("skills.duplicate_btn"), tr("skills.export_pick"))
@@ -328,6 +362,7 @@ class SkillsDialog(QDialog):
             self._reload()
 
     def _edit(self) -> None:
+        """Mở hộp thoại sửa skill đang chọn."""
         skill = self._current_skill()
         if skill is None:
             return
@@ -337,6 +372,7 @@ class SkillsDialog(QDialog):
             self._reload()
 
     def _delete(self) -> None:
+        """Xoá skill đang chọn sau khi hỏi xác nhận."""
         skill = self._current_skill()
         if skill is None:
             return
diff --git a/ui/spline_chart.py b/ui/spline_chart.py
index 6f0ce4a..f4f05fa 100644
--- a/ui/spline_chart.py
+++ b/ui/spline_chart.py
@@ -53,7 +53,11 @@ def _catmull_rom(points: List[QPointF]) -> QPainterPath:
 
 
 class SplineChart(QWidget):
+    """Biểu đồ đường cong mượt cho Dashboard: vẽ tay bằng ``QPainter``, không dùng
+    thư viện biểu đồ ngoài.
+    """
     def __init__(self):
+        """Biểu đồ đường cong mượt. Rỗng lúc đầu — dữ liệu vào qua ``set_data()``."""
         super().__init__()
         self._points: List[Tuple[str, float]] = []
         self._fmt: Callable[[float], str] = lambda v: f"{v:.2f}"
@@ -63,6 +67,9 @@ class SplineChart(QWidget):
 
     def set_data(self, points: List[Tuple[str, float]],
                  value_fmt: Optional[Callable[[float], str]] = None, title: str = "") -> None:
+        """Đặt dữ liệu cho biểu đồ: danh sách (nhãn, giá trị), kèm hàm định dạng giá
+        trị và tiêu đề.
+        """
         self._points = list(points or [])
         if value_fmt is not None:
             self._fmt = value_fmt
@@ -76,6 +83,9 @@ class SplineChart(QWidget):
         self.update()
 
     def paintEvent(self, _e):  # noqa: N802
+        """Vẽ biểu đồ: lưới mờ, đường cong Bézier mượt qua các điểm, vùng tô dưới đường
+        và nhãn trục.
+        """
         p = QPainter(self)
         p.setRenderHint(QPainter.Antialiasing)
         tok = current_palette()
diff --git a/ui/task_editor_dialog.py b/ui/task_editor_dialog.py
index ba608fa..89721ce 100644
--- a/ui/task_editor_dialog.py
+++ b/ui/task_editor_dialog.py
@@ -59,6 +59,12 @@ class TaskEditorDialog(QDialog):
 
     def __init__(self, task: Optional[dict] = None, all_tasks: Optional[List[dict]] = None,
                  parent=None, ctx=None):
+        """Form thêm/sửa một task theo lịch.
+
+        ``all_tasks`` để kiểm trùng tên và dựng danh sách task phụ thuộc. Danh sách
+        model của từng provider được nhớ lại sau khi nạp, để đổi provider qua lại
+        không phải gọi mạng lần nữa.
+        """
         super().__init__(parent)
         self._original = task
         self.ctx = ctx                     # for ✨ AI-generate buttons (optional)
@@ -521,16 +527,19 @@ class TaskEditorDialog(QDialog):
     # ---- helpers ---------------------------------------------------------
     @staticmethod
     def _select(combo: QComboBox, data) -> None:
+        """Chọn mục mang dữ liệu ``data`` trong một combo; không có thì để nguyên."""
         idx = combo.findData(data)
         if idx >= 0:
             combo.setCurrentIndex(idx)
 
     def _add_files(self) -> None:
+        """Thêm tệp vào danh sách dữ liệu đầu vào của task."""
         files, _ = QFileDialog.getOpenFileNames(self, tr("schedtask.pick_files"))
         for f in files:
             self.files_list.addItem(f)
 
     def _add_link(self) -> None:
+        """Thêm một link vào danh sách dữ liệu đầu vào của task."""
         url, ok = QInputDialog.getText(self, tr("schedtask.add_link_title"),
                                        tr("schedtask.add_link_label"))
         url = url.strip()
@@ -539,6 +548,7 @@ class TaskEditorDialog(QDialog):
 
     @staticmethod
     def _remove_selected(list_widget: QListWidget) -> None:
+        """Gỡ các dòng đang chọn khỏi một danh sách."""
         for item in list_widget.selectedItems():
             list_widget.takeItem(list_widget.row(item))
 
@@ -563,11 +573,13 @@ class TaskEditorDialog(QDialog):
         ctx = self.ctx
 
         def job(_worker: AgentWorker):
+            """Chạy nền: hỏi mọi provider danh sách model đang dùng được."""
             from ..core import preview_ai
 
             return preview_ai.fetch_live_models(ctx)
 
         def done(result: dict) -> None:
+            """Ghi nhớ danh sách model rồi nạp vào ô chọn."""
             self.load_models_btn.setEnabled(True)
             self._live_models = result or {}
             self._refresh_model_combo()
@@ -576,6 +588,7 @@ class TaskEditorDialog(QDialog):
                                         tr("schedtask.load_models_empty"))
 
         def failed(err: str) -> None:
+            """Nạp model lỗi: hiện cảnh báo và mở khoá lại nút."""
             self.load_models_btn.setEnabled(True)
             QMessageBox.warning(self, tr("schedtask.editor_title_new"), err)
 
@@ -586,6 +599,11 @@ class TaskEditorDialog(QDialog):
         w.start()
 
     def _check_chain(self) -> None:
+        """Kiểm tra chuỗi task nối tiếp có tạo thành vòng lặp không, và cảnh báo ngay
+        trên form.
+
+        Không chặn thì hai task trỏ vào nhau sẽ chạy vòng vô tận.
+        """
         candidates = self.all_tasks + ([self._original] if self._original else [self.task])
         err = chain_error(candidates, self.task["task_id"], self.next_combo.currentData())
         nxt_id = self.next_combo.currentData()
@@ -597,6 +615,7 @@ class TaskEditorDialog(QDialog):
         self.chain_warn.setText(warn)
 
     def _checked_depends_on(self) -> list:
+        """Id các task đang được tick trong danh sách phụ thuộc."""
         ids = []
         for i in range(self.depends_list.count()):
             item = self.depends_list.item(i)
@@ -621,12 +640,14 @@ class TaskEditorDialog(QDialog):
         ctx = self.ctx
 
         def job(worker: AgentWorker):
+            """Chạy nền: nhờ model soạn prompt cho task từ phần mô tả."""
             from ..core.ai_task_planner import generate_prompt_from_description
 
             return {"prompt": generate_prompt_from_description(
                 ctx.build_active_provider(), description, cancel=worker.is_cancelled)}
 
         def done(result: dict) -> None:
+            """Đổ prompt vừa soạn vào ô nội dung task."""
             self._gen_worker = None
             self.gen_desc_btn.setEnabled(True)
             self._apply_generated_prompt(result.get("prompt", ""), description)
@@ -690,6 +711,7 @@ class TaskEditorDialog(QDialog):
         self.manual_text.setPlainText(prompt or description_fallback)
 
     def _save(self) -> None:
+        """Kiểm tra hợp lệ rồi dựng bản ghi task từ form; thiếu tiêu đề thì không đóng."""
         title = self.title_edit.text().strip()
         if not title:
             QMessageBox.warning(self, tr("schedtask.editor_title_new"), tr("schedtask.title_required"))
diff --git a/ui/terminal_panel.py b/ui/terminal_panel.py
index 2d7a728..2703ba8 100644
--- a/ui/terminal_panel.py
+++ b/ui/terminal_panel.py
@@ -41,6 +41,7 @@ class _TermInput(QLineEdit):
     history_next = Signal()
 
     def keyPressEvent(self, e):  # noqa: N802 - Qt override
+        """Tab yêu cầu tự hoàn tất đường dẫn; Lên/Xuống duyệt lịch sử lệnh."""
         if e.key() == Qt.Key_Tab:
             self.complete_requested.emit()
             e.accept()
@@ -62,6 +63,11 @@ class TerminalPanel(QWidget):
     expanded = Signal()
 
     def __init__(self, parent=None):
+        """Terminal thu gọn ở đáy tab Thư mục.
+
+        Mở ở trạng thái gập lại; ``_hist_idx`` trỏ quá phần tử cuối khi không duyệt
+        lịch sử, nên mũi tên lên lần đầu ra lệnh gần nhất.
+        """
         super().__init__(parent)
         self._collapsed = True
         self._cwd = str(Path.home())
@@ -141,12 +147,14 @@ class TerminalPanel(QWidget):
 
     # ---- public API ----------------------------------------------------------
     def set_cwd(self, path: str) -> None:
+        """Đổi thư mục làm việc (bỏ qua nếu đường dẫn không tồn tại) và cập nhật dấu nhắc."""
         if path and os.path.isdir(path):
             self._cwd = os.path.normpath(str(path))
             self._cwd_lbl.setText(self._cwd)
             self._prompt.setText(_prompt_for(self._cwd))
 
     def toggle(self) -> None:
+        """Gập/mở panel; mở ra thì phát ``expanded`` để chỗ gọi trỏ shell về đúng thư mục."""
         self._collapsed = not self._collapsed
         self._apply_collapsed()
         if not self._collapsed:
@@ -154,10 +162,12 @@ class TerminalPanel(QWidget):
             self.input.setFocus()
 
     def set_collapsed(self, collapsed: bool) -> None:
+        """Đặt thẳng trạng thái gập/mở, không phát tín hiệu."""
         self._collapsed = collapsed
         self._apply_collapsed()
 
     def _apply_collapsed(self) -> None:
+        """Áp trạng thái gập/mở lên phần thân, icon và tooltip của nút."""
         self._body.setVisible(not self._collapsed)
         self._toggle_btn.setIcon(icon("chevron-right" if self._collapsed else "chevron-down"))
         self._toggle_btn.setToolTip(
@@ -165,6 +175,7 @@ class TerminalPanel(QWidget):
 
     # ---- history -------------------------------------------------------------
     def _history_move(self, direction: int) -> None:
+        """Đi lên/xuống trong lịch sử lệnh; đi quá cuối thì trả ô nhập về rỗng."""
         if not self._history:
             return
         self._hist_idx = max(0, min(len(self._history), self._hist_idx + direction))
@@ -172,6 +183,7 @@ class TerminalPanel(QWidget):
 
     # ---- Tab completion ------------------------------------------------------
     def _complete(self) -> None:
+        """Tự hoàn tất đường dẫn cho đoạn đang gõ (giống Tab của shell)."""
         text = self.input.text()
         head, sep, token = text.rpartition(" ")
         norm = token.replace("\\", "/")
@@ -191,6 +203,7 @@ class TerminalPanel(QWidget):
             return
 
         def _decorate(entry: str) -> str:
+            """Thêm dấu phân cách vào cuối tên nếu đó là thư mục."""
             full = os.path.join(base or self._cwd, entry)
             return entry + (os.sep if os.path.isdir(full) else "")
 
@@ -206,6 +219,7 @@ class TerminalPanel(QWidget):
 
     # ---- running commands ----------------------------------------------------
     def _run_current(self) -> None:
+        """Chạy lệnh đang gõ trong ô nhập rồi xoá ô."""
         cmd = self.input.text().strip()
         if not cmd:
             return
@@ -215,6 +229,9 @@ class TerminalPanel(QWidget):
         self.run_command(cmd)
 
     def run_command(self, cmd: str) -> None:
+        """Chạy một lệnh: ``clear``/``cls`` và ``cd`` xử lý tại chỗ, còn lại giao cho
+        tiến trình con.
+        """
         self._append(f"\n{_prompt_for(self._cwd)} {cmd}\n", role="cmd")
         stripped = cmd.strip()
         if stripped in ("clear", "cls"):
@@ -229,6 +246,11 @@ class TerminalPanel(QWidget):
         self._start_process(cmd)
 
     def _change_dir(self, target: str) -> None:
+        """Xử lý ``cd`` ngay trong panel.
+
+        Phải tự xử lý vì mỗi lệnh chạy trong một tiến trình riêng — ``cd`` giao cho
+        tiến trình con sẽ đổi thư mục của chính nó rồi biến mất cùng nó.
+        """
         target = target.strip()
         if target.lower().startswith("/d "):     # cmd's "cd /d X:\path" flag
             target = target[3:].strip()
@@ -247,6 +269,7 @@ class TerminalPanel(QWidget):
             self._append(tr("terminal.cd_error", path=target) + "\n", role="err")
 
     def _start_process(self, cmd: str) -> None:
+        """Khởi động tiến trình con chạy lệnh, đọc stdout/stderr theo luồng."""
         proc = QProcess(self)
         proc.setWorkingDirectory(self._cwd)
         proc.setProcessChannelMode(QProcess.SeparateChannels)
@@ -268,17 +291,20 @@ class TerminalPanel(QWidget):
             proc.start(os.environ.get("SHELL", "/bin/sh"), ["-c", cmd])
 
     def _on_finished(self, code: int, _status=None) -> None:
+        """Tiến trình kết thúc: in mã thoát (xanh nếu 0, đỏ nếu khác) và mở khoá ô nhập."""
         self._append(tr("terminal.exit", code=code) + "\n",
                      role="ok" if code == 0 else "err")
         self._set_running(False)
 
     def _set_running(self, running: bool) -> None:
+        """Khoá/mở ô nhập và nút Chạy theo trạng thái đang chạy."""
         self.input.setEnabled(not running)
         self._run_btn.setEnabled(not running)
         if not running:
             self.input.setFocus()
 
     def _append(self, text: str, role: str = "out") -> None:
+        """Nối văn bản vào khung kết quả, tô màu theo vai trò (lệnh / ra / lỗi / mã thoát)."""
         if not text:
             return
         from PySide6.QtGui import QColor, QTextCursor
@@ -295,10 +321,12 @@ class TerminalPanel(QWidget):
 
     # ---- lifecycle -----------------------------------------------------------
     def stop(self) -> None:
+        """Giết tiến trình đang chạy, nếu có."""
         if self._proc is not None and self._proc.state() != QProcess.NotRunning:
             self._proc.kill()
 
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn."""
         self._title.setText(tr("terminal.title"))
         self._run_btn.setText(tr("terminal.run"))
         self.input.setPlaceholderText(tr("terminal.placeholder"))
@@ -306,11 +334,18 @@ class TerminalPanel(QWidget):
 
 
 def _prompt_for(cwd: str) -> str:
+    """Dấu nhắc lệnh theo thư mục hiện tại: ``tên >`` trên Windows, ``tên $`` nơi khác."""
     name = Path(cwd).name or cwd
     return f"{name} >" if _IS_WIN else f"{name} $"
 
 
 def _decode(data: bytes) -> str:
+    """Giải mã đầu ra tiến trình con: thử UTF-8 trước, rồi tới bảng mã mặc định
+    của hệ điều hành.
+
+    Cần vì console Windows tiếng Việt/Nhật trả về cp1258/cp932 chứ không phải
+    UTF-8, giải mã cứng một bảng mã là ra chữ rác.
+    """
     import locale
     encs = ["utf-8"]
     try:
diff --git a/ui/workspace_tab.py b/ui/workspace_tab.py
index 82445cc..1c295aa 100644
--- a/ui/workspace_tab.py
+++ b/ui/workspace_tab.py
@@ -40,6 +40,7 @@ class _ProjectRow(QWidget):
     """
 
     def __init__(self, name: str, counts: str):
+        """Một dòng dự án trong danh sách: tên ở trên, số liệu tóm tắt ở dưới."""
         super().__init__()
         lay = QVBoxLayout(self)
         lay.setContentsMargins(6, 4, 6, 4)
@@ -52,6 +53,13 @@ class _ProjectRow(QWidget):
 
 
 class WorkspaceTab(QWidget):
+    """Trang chủ Workspace: cột project, cột lịch sử, và 5 sub-tab
+    (Dự án · Cowork · Co4E · Thư mục · GraphRAG).
+
+    Đây là chỗ CHỐT project đang hoạt động: :meth:`_bind_project` đặt
+    ``ctx.active_project_id``, và mọi chế độ theo-workspace (định tuyến, tự
+    chạy) đều phân giải theo giá trị đó.
+    """
     status_message = Signal(str)
     open_chat = Signal(str, dict)      # kind, conversation — open a thread in Cowork
     new_chat = Signal(str)             # project_id — start a new thread in this project
@@ -95,10 +103,12 @@ class WorkspaceTab(QWidget):
         return bool(0 <= index < self.tabs.count() and self.tabs.isTabVisible(index))
 
     def select_subtab(self, index: int) -> None:
+        """Chuyển sang sub-tab thứ ``index`` (thanh menu bên trái gọi vào đây)."""
         if 0 <= index < self.tabs.count():
             self.tabs.setCurrentIndex(index)
 
     def current_subtab(self) -> int:
+        """Chỉ số sub-tab đang mở."""
         return self.tabs.currentIndex()
 
     def hide_tab_bar(self) -> None:
@@ -107,6 +117,11 @@ class WorkspaceTab(QWidget):
         self.tabs.tabBar().hide()
 
     def __init__(self, ctx: AppContext, cowork=None, structure=None, sidebar=None):
+        """Màn Workspace: danh sách dự án bên trái, các tab con của dự án bên phải.
+
+        Cột lịch sử mở ở trạng thái gập cho tới khi người dùng chủ động mở ra, đúng
+        như bản vẽ bố cục màn này.
+        """
         super().__init__()
         self.ctx = ctx
         self._current_id = ""
@@ -255,6 +270,7 @@ class WorkspaceTab(QWidget):
 
     # ---- project settings tab -------------------------------------------
     def _build_project_tab(self) -> QWidget:
+        """Dựng sub-tab "Dự án": tên, mô tả, chỉ dẫn chung và thư mục sandbox."""
         right = QWidget()
         rl = QVBoxLayout(right)
         rl.setContentsMargins(8, 4, 4, 4)
@@ -311,6 +327,7 @@ class WorkspaceTab(QWidget):
 
     # ---- embedded sidebar (History inside the Cowork tab) ---------------
     def _wire_sidebar(self) -> None:
+        """Nối các tín hiệu của cột lịch sử vào màn Workspace."""
         sb = self._sidebar
         sb.open_chat.connect(self._on_sidebar_open)
         sb.new_chat.connect(self._on_sidebar_new)
@@ -354,6 +371,12 @@ class WorkspaceTab(QWidget):
         self._split.setSizes(sizes)
 
     def _on_sidebar_open(self, kind: str, conv: dict) -> None:
+        """Mở một hội thoại từ cột lịch sử, kèm chuyển sang đúng project của nó.
+
+        Id "default" (hội thoại cũ chưa gắn project) CỐ Ý không được coi là một
+        project thật — Cowork xử lý riêng nó như phạm vi toàn cục, không có tri thức
+        project nào.
+        """
         pid = conv.get("project_id", "") or "default"
         # The legacy "default"/no-project id is intentionally not a real
         # Project row (Cowork itself special-cases it as global/no-knowledge —
@@ -370,23 +393,30 @@ class WorkspaceTab(QWidget):
         self.open_chat.emit(kind or "cowork", conv)
 
     def _on_sidebar_new(self, kind: str) -> None:
+        """Bấm "chat mới" ở cột lịch sử: mở hội thoại mới rồi nhảy sang tab Cowork."""
         if self._cowork is not None:
             self._cowork.new_session()
         self._show_cowork_tab()
 
     def _on_sidebar_refresh(self) -> None:
+        """Cột lịch sử yêu cầu làm mới: cập nhật lại trạng thái Cowork và danh sách."""
         if self._cowork is not None:
             self._cowork.refresh_status()
         if self._sidebar is not None:
             self._sidebar.refresh()
 
     def _show_cowork_tab(self) -> None:
+        """Chuyển sang sub-tab Cowork nếu nó đang hiện."""
         if self._cowork_tab_idx >= 0:
             self.tabs.setCurrentIndex(self._cowork_tab_idx)
 
     def _on_tab_changed(self, idx: int) -> None:
         # Entering GraphRAG builds its (lazy) WebEngine view and scans the
         # project's sandbox; entering it is what keeps startup RAM low.
+        """Đổi sub-tab: vào GraphRAG mới dựng khung WebEngine và quét sandbox.
+
+        Dựng lười như vậy chính là thứ giữ cho RAM lúc khởi động ở mức thấp.
+        """
         if idx == self._graphrag_tab_idx and self._structure is not None:
             self._structure.auto_scan_and_fit()
         self._apply_pane_visibility()
@@ -450,6 +480,7 @@ class WorkspaceTab(QWidget):
 
     # ---- i18n ------------------------------------------------------------
     def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, gợi ý và tên các sub-tab."""
         self._header.setText(tr("workspace.header"))
         self._hint.setText(tr("workspace.hint"))
         self._projects_hdr.setText(tr("workspace.projects_heading").upper())
@@ -484,6 +515,7 @@ class WorkspaceTab(QWidget):
     _NARROW = 1500
 
     def showEvent(self, e):  # noqa: N802 - Qt override
+        """Lần hiện đầu tiên mới gắn bộ canh bố cục hẹp — trước đó chưa biết bề rộng thật."""
         super().showEvent(e)
         if getattr(self, "_narrow", None) is None:
             from .widgets import narrow_guard
@@ -511,6 +543,7 @@ class WorkspaceTab(QWidget):
             self._apply_pane_visibility()
 
     def _set_projects_collapsed(self, collapsed: bool) -> None:
+        """Gập/mở cột project, đổi giữa panel đầy đủ và dải mỏng."""
         strip_w = CollapseStrip.WIDTH + 2
         self._projects_panel.setVisible(not collapsed)
         self._projects_strip.setVisible(collapsed)
@@ -539,10 +572,25 @@ class WorkspaceTab(QWidget):
     def refresh_ai_models(self) -> None:
         """Reload the Folder tab's AI-edit model picker for the active provider —
         called when the active provider changes so the picker never keeps a
-        stale model list from the old provider."""
+        stale model list from the old provider.
+
+        R08-T12 moved the picker off ``FolderTab`` and onto the AI-Edit panel
+        (``ai_panel.resolver``). The old guard here tested for
+        ``folder.ai_model_combo``, an attribute that no longer exists on the
+        tab, so this hook silently did nothing and a provider switch left the
+        picker listing the previous provider's models. Reach the resolver
+        directly instead.
+
+        Refreshes unconditionally, exactly as the pre-refactor tab did. Gating
+        on "the picker already holds a list" looks tidier but breaks the case
+        that matters most: the first fetch failing (endpoint down, no network)
+        leaves the list empty, and the user switching provider afterwards is
+        precisely when the retry has to happen."""
         folder = getattr(self, "_folder", None)
-        if folder is not None and hasattr(folder, "ai_model_combo"):
-            folder.refresh_ai_models()
+        panel = getattr(folder, "ai_panel", None)
+        resolver = getattr(panel, "resolver", None)
+        if resolver is not None:
+            resolver.refresh()
 
     def refresh(self) -> None:
         """Re-list projects, keeping the current selection when possible. No
@@ -594,10 +642,12 @@ class WorkspaceTab(QWidget):
         return out
 
     def _selected_id(self) -> str:
+        """Id project đang chọn trong danh sách; '' nếu chưa chọn gì."""
         item = self.project_list.currentItem()
         return item.data(Qt.UserRole) if item else ""
 
     def _select_project_row(self, project_id: str) -> bool:
+        """Chọn dòng ứng với một project id; trả về ``False`` nếu không tìm thấy."""
         for i in range(self.project_list.count()):
             if self.project_list.item(i).data(Qt.UserRole) == project_id:
                 self.project_list.setCurrentRow(i)
@@ -605,9 +655,11 @@ class WorkspaceTab(QWidget):
         return False
 
     def _on_select(self, *_a) -> None:
+        """Đổi dòng chọn trong danh sách project: nạp project đó lên form."""
         self._load_current()
 
     def _load_current(self) -> None:
+        """Nạp project đang chọn lên form và nối mọi sub-tab vào nó."""
         from ..core.projects import load_project
 
         pid = self._selected_id()
@@ -664,6 +716,7 @@ class WorkspaceTab(QWidget):
         return [(p.name, p.project_id) for p in list_projects()]
 
     def selected_project_id(self) -> str:
+        """Id project đang chọn — lối vào công khai cho lớp ngoài."""
         return self._selected_id()
 
     def choose_project(self, project_id: str) -> bool:
@@ -736,6 +789,7 @@ class WorkspaceTab(QWidget):
         self._on_sidebar_new("cowork")
 
     def _set_tabs_busy(self, busy: bool) -> None:
+        """Khoá/mở các sub-tab phụ thuộc project trong lúc đang chuyển project."""
         for idx in (self._cowork_tab_idx, self._graphrag_tab_idx):
             if idx >= 0:
                 widget = self.tabs.widget(idx)
@@ -760,6 +814,12 @@ class WorkspaceTab(QWidget):
         # This is THE central project-switch hook — make the selected project the
         # ACTIVE workspace so per-workspace modes (routing + auto-run) resolve
         # against it, then refresh every surface's toggles to show its modes.
+        """Đặt project đang hoạt động và làm mới mọi thứ phụ thuộc nó.
+
+        Đây là hook chuyển project TRUNG TÂM: đặt ``ctx.active_project_id`` để chế
+        độ theo-workspace (định tuyến, tự chạy) phân giải đúng, rồi làm mới công
+        tắc trên từng bề mặt cho khớp.
+        """
         self.ctx.active_project_id = pid or "default"
         self._refresh_mode_toggles()
         if self._structure is not None:
@@ -794,6 +854,11 @@ class WorkspaceTab(QWidget):
 
     def _reload_threads(self) -> None:
         # The threads list was removed from the Project tab; nothing to reload.
+        """Nạp lại danh sách luồng chat của project.
+
+        Danh sách này đã bị gỡ khỏi tab Dự án nên thường là no-op; giữ lại để mã
+        cũ còn gọi tới không vỡ.
+        """
         if not hasattr(self, "threads"):
             return
         from ..core.history import list_conversations
@@ -812,6 +877,7 @@ class WorkspaceTab(QWidget):
 
     # ---- actions -----------------------------------------------------------
     def _create(self) -> None:
+        """Tạo project mới với tên mặc định rồi chọn nó."""
         from ..core.projects import new_project
 
         project = new_project(tr("workspace.default_new_name"))
@@ -822,6 +888,7 @@ class WorkspaceTab(QWidget):
         self.name_edit.selectAll()
 
     def _delete(self) -> None:
+        """Xoá project đang chọn sau khi hỏi xác nhận."""
         from ..core.projects import delete_project, load_project
 
         pid = self._selected_id()
@@ -839,6 +906,7 @@ class WorkspaceTab(QWidget):
         self.status_message.emit(tr("workspace.deleted", name=project.name))
 
     def _save(self) -> None:
+        """Lưu tên, mô tả và chỉ dẫn chung của project đang mở."""
         from ..core.projects import load_project, save_project
 
         pid = self._current_id
@@ -854,6 +922,7 @@ class WorkspaceTab(QWidget):
         self.status_message.emit(tr("workspace.saved", name=project.name))
 
     def _pick_folder(self) -> None:
+        """Chọn thư mục sandbox cho project đang mở."""
         from ..core.projects import load_project, save_project
 
         pid = self._current_id
@@ -870,6 +939,7 @@ class WorkspaceTab(QWidget):
         self.status_message.emit(tr("workspace.saved", name=project.name))
 
     def _open_workspace(self) -> None:
+        """Mở thư mục sandbox của project trong trình quản lý tệp của hệ điều hành."""
         from ..core.projects import load_project
 
         project = load_project(self._current_id) if self._current_id else None