diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6725ad4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# CLEANUP OLD NUGET
+
+清理 Gitea NuGet 套件舊版本的 Docker Action。
+
+## 行為
+
+- 預設保留每個套件最新 `2` 個版本。
+- 預設為 `dry_run=true`，只列出候選，不會真的刪除。
+- Gitea API token 的優先順序如下:
+  - `inputs.runner_token`
+  - `secrets.GITEA_TOKEN`
+  - `secrets.RUNNER_TOKEN`
+
+## Inputs
+
+| 名稱 | 預設值 | 說明 |
+| --- | --- | --- |
+| `runner_token` | - | 優先使用的 Gitea API token |
+| `keep_versions` | `2` | 每個套件要保留的最新版本數，必須是整數且 `>= 0` |
+| `dry_run` | `true` | `true` 只顯示刪除候選，`false` 才會呼叫 DELETE API |
+
+## Logs
+
+Action 會輸出可搜尋的 log，重點包括:
+
+- Token 來源
+- `keep_versions` 與 `dry_run`
+- 套件版本排序
+- 候選刪除清單
+- HTTP status 與 request id
+- Summary: `packages`、`versions`、`kept`、`candidates`、`deleted`、`skipped`、`errors`
+
+## 使用範例
+
+### Dry-run
+
+```yaml
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./
+        with:
+          runner_token: ${{ secrets.GITEA_TOKEN }}
+          keep_versions: 2
+          dry_run: true
+```
+
+### 實際刪除
+
+```yaml
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./
+        with:
+          runner_token: ${{ secrets.GITEA_TOKEN }}
+          keep_versions: 2
+          dry_run: false
+```
+
+## 測試
+
+- Shell 測試腳本: [`tests/entrypoint.sh`](tests/entrypoint.sh)
+- Gitea workflow: [`.gitea/workflows/ci.yaml`](.gitea/workflows/ci.yaml)
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..be30eab
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,21 @@
+# 開發階段狀態
+
+此檔保留原本的階段劃分，作為驗收參考與變更紀錄。
+
+## 已完成
+
+- Stage 1 - Token 取得與優先順序
+- Stage 2 - 保留舊版套件數量設定
+- Stage 3 - 列出套件與版本（Gitea API）
+- Stage 4 - 刪除邏輯與 dry-run 支援
+- Stage 5 - 日誌、錯誤處理與可觀測性
+- Stage 6 - 測試與 Gitea workflow CI
+- Stage 7 - 文件更新與發行準備
+
+## 驗收重點
+
+- Token 來源依序嘗試 `inputs.runner_token`、`secrets.GITEA_TOKEN`、`secrets.RUNNER_TOKEN`
+- `keep_versions` 預設為 `2`，且必須為整數 `>= 0`
+- 預設為 `dry_run=true`
+- log 會包含 package 列表、候選清單、HTTP status、request id 與 summary
+- CI 會執行 `tests/entrypoint.sh`