docs: update usage and stage status

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)