diff --git a/tools/write-confirm.sh b/tools/write-confirm.sh
index 38ab911..2349eac 100755
--- a/tools/write-confirm.sh
+++ b/tools/write-confirm.sh
@@ -12,6 +12,12 @@
 #   - JSC_GITEA_CONFIRM=no：直接拒絕。
 #   - 互動式執行：要求輸入「確認」。
 #   - 沒有互動終端：拒絕，避免默默寫出錯資料。
+# 結束碼: 0=已確認，呼叫端接著送出這次寫入。
+#         2=不要寫入，原因印在 stderr：缺動作名稱、缺目標名稱、JSC_GITEA_CONFIRM=no、
+#           輸入的不是「確認」、讀不到輸入，以及沒有互動終端這五種都走這一碼。
+#           呼叫端一律中止這次寫入，不要重試，也不要繞過確認直接呼叫 API。
+#   只有 0 與 2 兩種。用法錯誤與人工拒絕共用 2，因為兩者的處置一樣是「不寫」；
+#   拆成兩碼只會誘使呼叫端把用法錯誤當成可重試，反而寫出沒經過確認的資料。
 set -eu
 
 action="${1:-}"