diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ade622e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# AI Pull Request
+
+Gitea Docker Action：使用 [opencode](https://opencode.ai) 分析 `git diff`，自動產生 Pull Request 的標題與描述，並透過 Gitea token 建立 PR。
+
+## 功能
+
+1. 抓取**來源分支**與**目標分支**，計算兩者的差異（commits / stat / diff）。
+2. 呼叫 `opencode`（指定 `base_url` / `model` / `provider`）將 diff 總結成 PR 標題與描述（固定使用繁體中文）。
+   - 若 opencode 不可用或解析失敗，會自動以 commit 訊息與檔案統計產生 fallback 標題/描述。
+3. 偵測來源分支合併進目標分支是否會**衝突**：
+   - **無衝突**：直接建立 `來源分支 → 目標分支` 的 PR。
+   - **有衝突**：從**目標分支**建立解衝突分支，合併來源分支（保留衝突標記後 commit 並推送），再建立 `解衝突分支 → 來源分支` 的 PR，讓開發者在 PR 中手動解衝突；解決後來源分支即可順利合併回目標分支。
+
+## 輸入參數（inputs）
+
+| 參數 | 必填 | 說明 |
+| --- | --- | --- |
+| `source_branch` | ✅ | 來源分支 |
+| `target_branch` | ✅ | 目標分支 |
+| `opencode_base_url` | ✅ | opencode 使用的模型服務 base URL（OpenAI 相容端點） |
+| `opencode_model` | ✅ | opencode 使用的模型名稱 |
+| `opencode_provider` | ✅ | opencode provider 名稱 |
+
+## 使用範例
+
+```yaml
+name: AI PR
+on:
+  workflow_dispatch:
+    inputs:
+      source_branch:
+        description: '來源分支'
+        required: true
+      target_branch:
+        description: '目標分支'
+        required: true
+
+jobs:
+  ai-pull-request:
+    runs-on: ubuntu
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: AI Pull Request
+        uses: https://gitea.jsc.idv.tw/docker-actions/ai-pull-request@v1
+        with:
+          source_branch: ${{ inputs.source_branch }}
+          target_branch: ${{ inputs.target_branch }}
+          opencode_base_url: ${{ vars.OPENCODE_BASE_URL }}
+          opencode_model: ${{ vars.OPENCODE_MODEL }}
+          opencode_provider: ${{ vars.OPENCODE_PROVIDER }}
+```
+
+## 開發
+
+應用程式以 Node.js 開發，位於 [`app/`](app/)，進入點為 [`entrypoint.sh`](entrypoint.sh) → `node /app/index.js`。
+
+```
+app/
+├── index.js          # 主流程
+└── lib/
+    ├── inputs.js      # 讀取/驗證環境變數
+    ├── git.js         # git 操作（fetch / diff / 衝突偵測 / 解衝突分支）
+    ├── gitea.js       # Gitea API（建立 PR）
+    ├── opencode.js    # 呼叫 opencode 產生標題與描述
+    └── util.js        # 共用工具（執行指令、日誌、遮蔽敏感資訊）
+```
+
+語法檢查：
+
+```bash
+cd app && node --check index.js
+```