diff --git a/README.md b/README.md
index 110f91e..f521cbb 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,66 @@
-# blog-embedding
+# Blog Embedding Tools
 
-產生所有文章的 embedding，並做相似度搜尋。
\ No newline at end of file
+Docusaurus blog 文章的 embedding 產生 + 相似度查詢。用 Ollama 本地跑，不吃外部 API。
+
+## 前置
+
+```bash
+# 系統
+brew install fzf        # macOS，Linux 用 apt install fzf
+
+# Ollama
+ollama pull qwen3-embedding:8b
+
+# Python
+pip install pyyaml requests numpy iterfzf
+```
+
+## 檔案說明
+
+| 檔案 | 用途 |
+|---|---|
+| `blog_embeddings.py` | 掃描 blog 資料夾，為每篇文章產生 embedding，存成 JSON |
+| `blog_similarity.py` | 讀取 JSON，模糊搜尋選一篇文章，列出最相似 / 最不相似的文章 |
+| `blog_embeddings.json` | 輸出的資料檔（自動產生，記得加進 `.gitignore`） |
+
+## 使用
+
+### 1. 產生 embedding
+
+先到 `blog_embeddings.py` 改 `BLOG_DIR` 指向你的 blog 路徑，然後：
+
+```bash
+# 增量模式（預設）：只跑新文章或改過的文章
+python blog_embeddings.py
+
+# 全部重跑
+python blog_embeddings.py --full
+```
+
+### 2. 查相似度
+
+```bash
+python blog_similarity.py
+```
+
+會跳出 fzf 模糊搜尋，打字過濾、上下鍵選文章，選完印出結果。
+
+## JSON 結構
+
+```json
+{
+  "slug": "/my-post",
+  "title": "文章標題",
+  "file": "./blog/2024-01-01/index.md",
+  "hash": "sha256...",
+  "embedding": [0.012, -0.034, ...]
+}
+```
+
+`hash` 是檔案內容的 SHA-256，增量模式靠它判斷文章有沒有改過。
+
+## 備註
+
+- Embedding model 用的是 `qwen3-embedding:8b`，中文表現很好
+- 文章的 frontmatter 必須有 `slug` 才會被處理，沒有的會跳過
+- 不會動到任何原始 blog 檔案
\ No newline at end of file