diff --git a/README.en.md b/README.en.md
new file mode 100644
index 0000000..9cd5337
--- /dev/null
+++ b/README.en.md
@@ -0,0 +1,91 @@
+# gitea-pr-review
+
+> English documentation | 中文: [README.md](./README.md)
+
+`gitea-pr-review` fetches Gitea Pull Requests and converts them into LLM-friendly documents.
+
+## Features
+
+- Fetch core PR context: title, status, branches, commit list, and basic diff stat
+- Preserve review/comment/reply content in full
+- Two output formats:
+  - `markdown`: ready for direct LLM input
+  - `json`: structured output for automation and post-processing
+- Re-render Markdown from existing JSON without calling Gitea again
+
+## Build
+
+```bash
+cargo build --release
+# binary: target/release/gitea-pr-review
+```
+
+## Environment Variables
+
+Required for the `fetch` subcommand:
+
+- `GITEA_PR_CLI_API_TOKEN`
+- `GITEA_PR_CLI_URL` (for example: `https://gitea.com`)
+- `GITEA_PR_CLI_REPO` (for example: `Origami404/aaa`)
+
+## Usage
+
+### 1) Fetch from Gitea (`fetch`)
+
+```bash
+# default: markdown to stdout
+gitea-pr-review fetch <pr-index>
+
+# json to stdout
+gitea-pr-review fetch <pr-index> --format json
+
+# write to file
+gitea-pr-review fetch <pr-index> --out pr.md
+gitea-pr-review fetch <pr-index> --format json --out pr.json
+```
+
+### 2) Render Markdown from JSON (`render-md`)
+
+```bash
+# to stdout
+gitea-pr-review render-md --in pr.json
+
+# to file
+gitea-pr-review render-md --in pr.json --out pr.md
+```
+
+## Markdown Output Shape (Example)
+
+````md
+# <repo> `#<pr-index>` <pr-title>
+
+## Metadata
+
+### Commits
+- <sha-short> <title> (<author>, <date>)
+
+### Diff Stat
+total: <files_changed> files, +<additions>, -<deletions>
+- <file-path>: +<additions>, -<deletions>
+
+## Review 1 (<review-state>)
+> <reviewer>
+
+### Comment 1.1
+<file>:<line>
+<user>:
+```md
+<original comment body>
+```
+
+### Reply 1.1.1
+<user>:
+```md
+<original reply body>
+```
+````
+
+## Notes
+
+- Output goes to `stdout` by default; use `--out` to write a file.
+- The renderer preserves markdown-heavy comment bodies safely by adjusting code fences when needed.
diff --git a/README.md b/README.md
index e18fb5b..ca8aa13 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,38 @@
-这是一个读取 Gitea PR，并将其内容整理为 LLM 友好的文档的项目。
+# gitea-pr-review
 
-主要输出两种格式：
+> 中文文档（默认） | English: [README.en.md](./README.en.md)
 
-1. `markdown`：直接面向 LLM 的可读文档，重点保留 review/comment/reply 内容。
-2. `json`：结构化输出，便于二次处理。
+`gitea-pr-review` 用于读取 Gitea Pull Request，并整理为适合 LLM 消费的文档。
 
-使用：
+## 功能
+
+- 拉取单个 PR 的核心信息：标题、状态、分支、commit 列表、基础 diff stat
+- 完整保留 review/comment/reply 原文
+- 支持两种输出格式：
+  - `markdown`：适合直接喂给 LLM
+  - `json`：结构化输出，便于脚本二次处理
+- 支持从已保存的 JSON 重新渲染 Markdown（无需再次请求 Gitea）
+
+## 安装
 
 ```bash
-GITEA_PR_CLI_API_TOKEN=...
-GITEA_PR_CLI_URL=https://gitea.com
-GITEA_PR_CLI_REPO=Origami404/aaa
+cargo build --release
+# 可执行文件：target/release/gitea-pr-review
+```
 
+## 环境变量
+
+`fetch` 子命令需要以下环境变量：
+
+- `GITEA_PR_CLI_API_TOKEN`
+- `GITEA_PR_CLI_URL`（例如 `https://gitea.com`）
+- `GITEA_PR_CLI_REPO`（例如 `Origami404/aaa`）
+
+## 用法
+
+### 1) 从 Gitea 拉取 PR（fetch）
+
+```bash
 # 默认输出 markdown 到 stdout
 gitea-pr-review fetch <pr-index>
 
@@ -19,17 +40,23 @@ gitea-pr-review fetch <pr-index>
 gitea-pr-review fetch <pr-index> --format json
 
 # 输出到文件
-gitea-pr-review fetch <pr-index> --format json --out pr.json
 gitea-pr-review fetch <pr-index> --out pr.md
+gitea-pr-review fetch <pr-index> --format json --out pr.json
+```
 
-# 从已有 json 重新生成 markdown
+### 2) 从 JSON 渲染 Markdown（render-md）
+
+```bash
+# 输出到 stdout
 gitea-pr-review render-md --in pr.json
+
+# 输出到文件
 gitea-pr-review render-md --in pr.json --out pr.md
 ```
 
-返回的 markdown 结构大致如下：
+## Markdown 输出结构（示例）
 
-`````md
+````md
 # <repo> `#<pr-index>` <pr-title>
 
 ## Metadata
@@ -38,9 +65,7 @@ gitea-pr-review render-md --in pr.json --out pr.md
 - <sha-short> <title> (<author>, <date>)
 
 ### Diff Stat
-- files changed: <n>
-- additions: <n>
-- deletions: <n>
+total: <files_changed> files, +<additions>, -<deletions>
 - <file-path>: +<additions>, -<deletions>
 
 ## Review 1 (<review-state>)
@@ -58,4 +83,9 @@ gitea-pr-review render-md --in pr.json --out pr.md
 ```md
 <原始回复正文>
 ```
-`````
+````
+
+## 说明
+
+- 默认输出到 `stdout`；仅在指定 `--out` 时写入文件。
+- 当评论正文本身包含 Markdown / 代码块时，渲染器会自动处理 fence，避免破坏整体结构。
diff --git a/docs/idea.md b/docs/idea.md
new file mode 100644
index 0000000..e18fb5b
--- /dev/null
+++ b/docs/idea.md
@@ -0,0 +1,61 @@
+这是一个读取 Gitea PR，并将其内容整理为 LLM 友好的文档的项目。
+
+主要输出两种格式：
+
+1. `markdown`：直接面向 LLM 的可读文档，重点保留 review/comment/reply 内容。
+2. `json`：结构化输出，便于二次处理。
+
+使用：
+
+```bash
+GITEA_PR_CLI_API_TOKEN=...
+GITEA_PR_CLI_URL=https://gitea.com
+GITEA_PR_CLI_REPO=Origami404/aaa
+
+# 默认输出 markdown 到 stdout
+gitea-pr-review fetch <pr-index>
+
+# 输出 json 到 stdout
+gitea-pr-review fetch <pr-index> --format json
+
+# 输出到文件
+gitea-pr-review fetch <pr-index> --format json --out pr.json
+gitea-pr-review fetch <pr-index> --out pr.md
+
+# 从已有 json 重新生成 markdown
+gitea-pr-review render-md --in pr.json
+gitea-pr-review render-md --in pr.json --out pr.md
+```
+
+返回的 markdown 结构大致如下：
+
+`````md
+# <repo> `#<pr-index>` <pr-title>
+
+## Metadata
+
+### Commits
+- <sha-short> <title> (<author>, <date>)
+
+### Diff Stat
+- files changed: <n>
+- additions: <n>
+- deletions: <n>
+- <file-path>: +<additions>, -<deletions>
+
+## Review 1 (<review-state>)
+> <reviewer>
+
+### Comment 1.1
+<file>:<line>
+<user>:
+```md
+<原始评论正文>
+```
+
+### Reply 1.1.1
+<user>:
+```md
+<原始回复正文>
+```
+`````