From 978e3604c09efc9b83490d9a0a2ef19ddb43fd78 Mon Sep 17 00:00:00 2001
From: black_zero <blackzero35800@gmail.com>
Date: Sun, 1 Mar 2026 23:52:03 +0800
Subject: [PATCH] docs: update readme

---
 README.md       | 43 +++++++++++++++++++++++++++++++++++--------
 README.zh-CN.md | 43 +++++++++++++++++++++++++++++++++++--------
 2 files changed, 70 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index f8e6db9..83d5e27 100644
--- a/README.md
+++ b/README.md
@@ -84,15 +84,42 @@ You can run classification without changing prompts, or customize prompts for:
 - existing-list constrained modes
 - English/Chinese prompt variants
 
-## Typical Workflow
+## Usage Guide
 
-1. Connect PAT.
-2. Click `Sync Star Lists`.
-3. (Optional) Retry failed list membership scans from the status panel.
-4. Open `Run Classification` and run LLM classification.
-5. Review preview and diffs.
-6. Open `Apply Updates` to preview planned GitHub changes.
-7. Apply updates to GitHub.
+### Step 1: Obtain a GitHub Personal Access Token
+
+1. Go to [https://github.com/settings/tokens](https://github.com/settings/tokens).
+2. Click **Generate new token** → **Generate new token (classic)**.
+3. Give it a descriptive name (e.g. `star-manager`).
+4. Grant the following permission scopes:
+   - **repo** — all permissions under `repo`
+   - **user** — all permissions under `user`
+5. Click **Generate token** and copy the generated token.
+
+After obtaining the token, open the app and click **Sync Star Lists** to verify that the token works and your starred repositories can be synced successfully.
+
+### Step 2: Configure the App
+
+#### GitHub Token
+
+1. Open the app's **Settings** page (or click **Connect PAT**).
+2. Paste the token you generated in Step 1.
+3. Click **Validate** to verify and save.
+
+#### LLM Configuration
+
+1. In **Settings → LLM Configuration**, fill in:
+   - **Base URL** — the endpoint of your OpenAI-compatible LLM service.
+   - **API Key** — your LLM API key.
+   - **Model Name** — the model to use for classification.
+2. Click **Run Classification** to start the classification pipeline.
+3. It is recommended to use **Test Mode** first to run a small sample and verify that the model is working correctly before processing all repositories.
+
+### Step 3: Apply Updates to GitHub
+
+1. After classification is complete, review the diff preview.
+2. Click **Apply Updates** to push the classification results (Star List assignments) to your GitHub account.
+3. The app will create any missing Star Lists and update repository memberships accordingly.
 
 ## Project Structure
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 4ab4ef7..915ada3 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -84,15 +84,42 @@ pnpm preview
 - 基于 Existing Lists 的约束模式
 - 中英文 Prompt 变体
 
-## 典型使用流程
+## 使用指南
 
-1. 连接 PAT。
-2. 点击 `Sync Star Lists`。
-3. （可选）在状态面板重试失败的列表成员扫描。
-4. 打开 `Run Classification` 执行分类。
-5. 查看分类预览与差异视图。
-6. 打开 `Apply Updates` 查看将写回 GitHub 的变更。
-7. 执行写回。
+### 第一步：获取 GitHub Personal Access Token
+
+1. 访问 [https://github.com/settings/tokens](https://github.com/settings/tokens)。
+2. 点击 **Generate new token** → **Generate new token (classic)**。
+3. 填写一个描述性名称（如 `star-manager`）。
+4. 授予以下权限范围：
+   - **repo** — 勾选 `repo` 下的所有权限
+   - **user** — 勾选 `user` 下的所有权限
+5. 点击 **Generate token** 并复制生成的 Token。
+
+获取 Token 后，打开应用并点击 **Sync Star Lists**，验证 Token 是否正常工作、能否成功同步你的 Star 仓库列表。
+
+### 第二步：配置应用
+
+#### GitHub Token
+
+1. 打开应用的 **Settings** 页面（或点击 **Connect PAT**）。
+2. 粘贴在第一步生成的 Token。
+3. 点击 **Validate** 进行验证并保存。
+
+#### LLM 配置
+
+1. 在 **Settings → LLM Configuration** 中填写：
+   - **Base URL** — 你的 OpenAI 兼容 LLM 服务端点地址。
+   - **API Key** — 你的 LLM API 密钥。
+   - **Model Name** — 用于分类的模型名称。
+2. 点击 **Run Classification** 开始分类流程。
+3. 建议先使用 **测试模式（Test Mode）** 运行小样本，确认模型工作正常后再处理全部仓库。
+
+### 第三步：应用更新至 GitHub
+
+1. 分类完成后，查看差异预览（Diff Preview）。
+2. 点击 **Apply Updates**，将分类结果（Star List 分配）推送到你的 GitHub 账号。
+3. 应用会自动创建缺失的 Star Lists，并更新仓库的列表归属关系。
 
 ## 项目结构