diff --git a/.gitea/workflows/cd.yaml b/.gitea/workflows/cd.yaml
index 30b1952..7d58a9c 100644
--- a/.gitea/workflows/cd.yaml
+++ b/.gitea/workflows/cd.yaml
@@ -1,12 +1,27 @@
+# =============================================================================
+# 用途: release-cleanup 專案的 CD workflow。
+#       在程式碼推送至 master 分支時,自動釋出並標註 (tag) 成品版本。
+# 更新日期: 2026/06/26 10:28:36
+# =============================================================================
+
+# workflow 名稱,顯示於 Gitea Actions 介面。
 name: CD
+# 觸發條件設定。
 on:
+  # 於 push 事件觸發。
   push:
+    # 僅在推送至 master 分支時觸發。
     branches:
     - master
 jobs:
+  # job 識別碼:釋出並標註版本。
   release-tag-version:
+    # job 顯示名稱。
     name: Release Tag Version
+    # 指定執行於 ubuntu runner。
     runs-on: ubuntu
     steps:
+    # 呼叫共用的 release-tag-version composite action,自動產生版本標籤並釋出。
     - name: 釋出並標註成品版本
+      # 版本以變數 ACTION_RELEASE_TAG_VERSION 控制,便於統一升級。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml
index b9d4eed..12cd0bc 100644
--- a/.gitea/workflows/ci.yaml
+++ b/.gitea/workflows/ci.yaml
@@ -1,19 +1,40 @@
+# =============================================================================
+# 用途: release-cleanup 專案的 CI workflow。
+#       在 Pull Request 開啟或更新時,觸發 OpenCode AI 程式碼審查。
+# 更新日期: 2026/06/26 10:28:36
+# =============================================================================
+
+# workflow 名稱,顯示於 Gitea Actions 介面。
 name: CI
+# 觸發條件設定。
 on:
+  # 於 Pull Request 事件觸發。
   pull_request:
+    # 忽略目標分支為 master 的 PR (master 走 CD 流程,不在此審查)。
     branches-ignore:
     - master
+    # 僅在 PR 開啟 (opened) 或有新 commit 推送 (synchronize) 時觸發。
     types: [opened, synchronize]
 jobs:
+  # job 識別碼:AI 程式碼審查。
   ai-code-review:
+    # job 顯示名稱。
     name: AI Code Review
+    # 指定執行於 ubuntu runner。
     runs-on: ubuntu
+    # 此 job 所需的權限 (供 AI 寫回審查結果)。
     permissions:
+      # 可寫入儲存庫內容。
       contents: write
+      # 可在 PR 上留言/變更狀態。
       pull-requests: write
+      # 可建立/更新 issue。
       issues: write
     steps:
+    # 呼叫共用的 OpenCode 程式碼審查 composite action。
     - name: AI 程式碼審查 by OpenCode
+      # 版本以變數 ACTION_OPENCODE_CODE_REVIEW_VERSION 控制,便於統一升級。
       uses: https://gitea.jsc.idv.tw/composite-actions/opencode-code-review@${{ vars.ACTION_OPENCODE_CODE_REVIEW_VERSION }}
       with:
+        # 傳入留言用 token (secret),供 action 在 PR 上發表審查留言。
         comment_token: ${{ secrets.COMMENT_TOKEN }}
diff --git a/app/index.js b/app/index.js
index fceefc1..4cb2d44 100644
--- a/app/index.js
+++ b/app/index.js
@@ -6,6 +6,14 @@ import { cleanupReleases } from './releases.js'
 import { cleanupOrphanTags } from './tags.js'
 import { separator, fail } from './logger.js'
 
+/**
+ * Action 主流程:讀取並驗證環境設定、建立帶認證的 Gitea 客戶端,
+ * 先清理超出保留數量的舊 release,再清理未被任何 release 指定的孤立 tag,最後輸出結尾分隔線。
+ *
+ * 任一步驟拋出的例外不在此攔截,改由模組層級的 `main().catch(...)` 統一處理並以非零狀態結束。
+ *
+ * @returns {Promise<void>} 流程完成時 resolve;設定驗證或讀取 API 失敗時 reject。
+ */
 async function main() {
   const config = loadConfig()
   const client = new GiteaClient({ token: config.token })