diff --git a/README.md b/README.md
index 4045e9a..797f1ca 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
+
+ English · 繁體中文
+
+
**Tiny engine, immense model.** Run **GLM-5.2 (744B-parameter MoE)** on a consumer machine with ~25 GB of RAM — in pure C, with zero dependencies, by streaming experts from disk.
Colibrì is a lightweight, quality-preserving MoE runtime that treats VRAM, RAM,
diff --git a/README.zh-TW.md b/README.zh-TW.md
new file mode 100644
index 0000000..1662617
--- /dev/null
+++ b/README.zh-TW.md
@@ -0,0 +1,233 @@
+
+
+
+
+
+ English · 繁體中文
+
+
+**小巧引擎，龐大模型。**只要約 25 GB 記憶體，就能在消費級電腦上執行 **GLM-5.2（744B 參數的 MoE）**——以零相依套件的純 C 實作，從硬碟串流載入專家。
+
+Colibrì 是一套輕量、維持品質的 MoE 執行環境，將 VRAM、RAM
+與儲存裝置視為統一管理的記憶體階層。高速記憶體不足可能降低速度，
+但預設策略**絕不會在未告知的情況下改變模型精度或路由語意**。
+
+```
+$ ./coli chat
+ 🐦 colibrì v1.0 — GLM-5.2 · 744B MoE · int4 · streaming CPU
+ ✓ ready in 32s · resident 9.9 GB
+ › ciao!
+ ◆ Ciao! 😊 Come posso aiutarti oggi?
+```
+
+## 實際運行畫面
+
+
+ 
+
+網頁儀表板（./coli web）：744B 模型達到 4 tok/s、TTFT 1.6 秒、硬碟讀取 0——
+在 6× RTX 5090 上讓所有專家常駐，並即時顯示 token 指標、每輪耗時明細、
+VRAM／RAM／硬碟層級長條，以及角落的即時迷你大腦。
+
+
+ 
+
+大腦（Brain）頁面：將全部 19,456 個專家呈現為活的皮質——顏色代表儲存層級，
+亮度代表路由熱度，每輪被路由到的專家都會閃白。將游標停在專家上，即可查看其
+實測主題親和度。
+
+
+ 
+
+圖譜（Atlas）頁面：將實測專家圖譜
+呈現為 3D 星系——共 13,260 個已分析專家，其中 1,041 個可重現的專門專家會按主題聚集
+（詩歌、法律、中文、SQL……）。位置取自實測路由親和度，而非學習出的嵌入向量。拖曳即可旋轉。
+
+## 核心概念
+
+744B 的專家混合（Mixture-of-Experts）模型，每個 token 只會啟用約 40B 參數——
+其中每個 token 之間會變動的只有約 11 GB（被路由到的專家）：
+
+
+ 
+
+
+所以模型不必完整**放進**高速記憶體，而是需要正確**配置位置**：
+
+- **稠密部分**（注意力、共享專家、嵌入——約 17B 參數）以 int4
+ **常駐 RAM**（約 9.9 GB）；
+- **19,456 個路由專家**（75 個 MoE 層 × 256，加上 MTP head；每個在 int4 下約 19 MB）
+ **存放在硬碟**（約 370 GB），並**隨需串流載入**，搭配逐層 LRU 快取、
+ 會學習的熱門專家固定儲存區，以及選用的 VRAM 層級。
+
+引擎由單一 C 檔（`c/glm.c`）與少量標頭檔組成。不需要 BLAS，
+執行階段不需要 Python，也不需要 GPU。
+
+## 運作方式
+
+### 每個 token 的處理路徑
+
+
+ 
+
+
+每個 token 的每一層都會走過相同的五個步驟。設計目標是讓
+**配置只決定速度**——無論專家是從 VRAM 或硬碟回應，路由器的決策與權重精度都完全相同。
+
+### 統一記憶體階層，取代單一記憶體門檻
+
+
+ 
+
+
+同一套引擎涵蓋完整硬體範圍：在 25 GB 筆電上，一切都從硬碟串流載入
+（慢，但結果正確）；在大型主機上，則可讓整組專家常駐
+（`CUDA_EXPERT_GB=auto PIN_GB=all`），讓硬碟完全退出解碼路徑。
+兩端之間有一層**學習型快取**：引擎會記錄*你的*工作負載路由到哪些專家
+（`.coli_usage`，每輪更新），並自動固定最熱門的專家——colibrì 確實會越用越快。
+在多插槽主機上，`COLI_NUMA=1` 會將常駐權重交錯分配到各記憶體控制器
+（[#82](https://github.com/JustVugg/colibri/issues/82)）。
+
+### 絕不為同一次硬碟讀取等待兩遍
+
+快取未命中的成本很高，因此引擎大部分的巧思都用來避免或重疊處理這些讀取：
+每個專家的三個矩陣相鄰儲存，並以一次 `pread` 讀取；有界非同步 I/O pool
+（`PIPE=1`，預設啟用）會在常駐專家運算時載入缺少的專家；批次位置只讀取每個
+不重複專家一次（**批次聯集**）；路由前瞻執行緒（`PILOT=1`）則預先載入下一層專家——
+實測顯示，路由結果提前一層時有 **71.6% 的可預測性**。
+在 GPU 上，常駐管線（`COLI_CUDA_PIPE=2`）讓殘差流跨層保留在裝置端，
+使 CPU 專家迴圈不中斷；在 Apple Silicon 上，實驗性的
+[Metal 後端](docs/metal.md)會用統一記憶體 GPU 執行批次專家運算。
+
+### 忠實模型，壓縮狀態
+
+前向傳遞已透過 `transformers` oracle 驗證為**逐 token 完全一致**
+（teacher-forcing 32/32）。MLA 注意力儲存壓縮後的 KV 狀態——每個 token 為 576 個
+浮點數，而非 32,768 個（**縮小 57×**）——並跨重新啟動持久保存
+（`.coli_kv`）：對話可暖啟恢復，不需重新 prefill，結果與不中斷的工作階段
+逐位元組相同。DSA 稀疏注意力（GLM-5.2 的 lightning indexer）已忠實實作，
+並透過強制選取所有 key，驗證可精確重現稠密注意力。
+
+### 如實呈現推測式解碼
+
+GLM-5.2 原生 MTP head 會起草 token，再由主模型以一次批次前向傳遞驗證——
+條件合適時每次 forward 可產生 2.2–2.8 個 token。兩條得來不易的規則已成為預設值：
+MTP head 必須是 **int8**（int4 head 的接受率會崩落到 0–4%，見
+[#8](https://github.com/JustVugg/colibri/issues/8)），且草稿與驗證必須計算
+**相同函數**——`SPEC_PIN=1` 會把兩者固定在同一 kernel family
+（完整鑑識過程見 [#163](https://github.com/JustVugg/colibri/issues/163)）。
+文法強制草稿（[`GRAMMAR=file.gbnf`](docs/grammar-draft.md)）可在受限 JSON 輸出中，
+以近乎免費的成本提高接受率。推測式解碼是否帶來淨收益取決於快取熱度——請實測，
+若不划算就使用 `DRAFT=0`。
+
+## 實際成果
+
+
+ 
+
+
+同一套引擎、同一個 int4 容器——硬體只會改變專家的存放位置。
+[完整 benchmark 表格](docs/benchmarks.md)中的重點如下：
+
+- **6× RTX 5090，全部常駐：**解碼 5.8–6.8 tok/s，TTFT 約 13 秒
+ （[實驗紀錄](docs/experiments/glm52-6x5090-2026-07-12.md)）；
+- **128 GB、僅使用 CPU 的桌上型電腦：**暖機後約 1.8 tok/s
+ （[#200](https://github.com/JustVugg/colibri/issues/200)）；
+- **單張 RTX 5070 Ti 的筆電級電腦：**透過 GPU 常駐管線達到 1.07 tok/s
+ （[#273](https://github.com/JustVugg/colibri/issues/273)）；
+- **25 GB 開發機：**冷啟動 0.05–0.1 tok/s——這是專案起步時已證實的下限，
+ 也仍是如實呈現的基準。
+
+品質來自測量，而非假設：int4 容器的量化成本，以及 scale granularity／rotation
+消融實驗，收錄於 [docs/benchmarks.md](docs/benchmarks.md#quality-benchmark)、
+[#108](https://github.com/JustVugg/colibri/issues/108) 與
+[#81](https://github.com/JustVugg/colibri/issues/81)。
+
+## 開始使用
+
+### 1. 取得模型
+
+Hugging Face 上已有預先轉換的 **GLM-5.2 int4** 容器——請務必使用
+**含 int8 MTP head 的版本**：
+
+**https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp**
+
+> ⚠️ 原始鏡像使用 int4 MTP head → 草稿接受率為 0%
+>（[#8](https://github.com/JustVugg/colibri/issues/8)）。請檢查你的版本：
+> `ls -l /out-mtp-*`——正確的 int8 大小為 `3527131672 / 5366238584 / 1065950496`。
+
+你也可以自行從 FP8 來源轉換——只需一條可續傳的指令，且任何時候都不需要
+在硬碟上同時存放完整的 756 GB：
+
+```bash
+cd c && ./setup.sh # 檢查 gcc/OpenMP、建置並執行自我測試
+./coli convert --model /nvme/glm52_i4 # 逐 shard 下載並轉換（僅此一次需要 python）
+```
+
+### 2. 執行
+
+```bash
+COLI_MODEL=/nvme/glm52_i4 ./coli chat # 自動偵測 RAM 預算、快取與 MTP
+COLI_MODEL=/nvme/glm52_i4 ./coli plan # 檢視規劃的 VRAM／RAM／硬碟配置
+COLI_MODEL=/nvme/glm52_i4 ./coli doctor # 唯讀就緒檢查
+./coli web --model /nvme/glm52_i4 # 在同一個連接埠提供 API 與網頁儀表板
+./coli serve --model /nvme/glm52_i4 # 僅提供 OpenAI 相容 API
+```
+
+引擎執行階段是純 C——python 只供單次轉換工具與選用的 API gateway 使用。
+
+### 3. 深入了解
+
+| 主題 | 文件 |
+|---|---|
+| Benchmark、社群實測數據、品質測量 | [docs/benchmarks.md](docs/benchmarks.md) |
+| 調校選項、策略、學習型快取、預先載入 | [docs/tuning.md](docs/tuning.md) |
+| Windows 11 原生建置（含 CUDA DLL） | [docs/windows.md](docs/windows.md) |
+| CUDA 後端、VRAM 專家層級、全部常駐 | [docs/cuda.md](docs/cuda.md) |
+| Apple Silicon Metal 後端 | [docs/metal.md](docs/metal.md) |
+| OpenAI 相容 API、KV slots、網頁儀表板 | [docs/api.md](docs/api.md) |
+| 文法強制草稿（結構化輸出） | [docs/grammar-draft.md](docs/grammar-draft.md) |
+| 環境變數完整清單 | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) |
+
+## 支持專案
+
+colibrì 最初是由一人使用 12 核心、25 GB RAM 的筆電開發；
+如今它的數據來自社群中的各種真實機器。如果這個專案對你有用：
+
+- ⭐ 為儲存庫加星並分享；
+- 🐛 以 issue 提交你的硬體 benchmark 數據——實測資料比任何其他事都更能推動專案；
+- 💬 若想贊助開發或捐贈硬體，請透過 GitHub issues 聯絡。
+
+## 儲存庫結構
+
+```
+Makefile 根目錄建置／檢查入口
+c/
+├── glm.c 單檔 GLM 引擎
+├── st.h, tok.h, json.h 執行階段標頭檔
+├── backend_cuda.* 選用的 CUDA 層級
+├── Makefile 建置與本機檢查
+├── coli 使用者介面 CLI
+├── openai_server.py OpenAI 相容 HTTP gateway
+├── setup.sh 單一指令完成本機設定
+├── tools/ 離線轉換、fixtures 與 benchmarks
+├── scripts/ 長時間轉換輔助工具
+└── tests/ 零相依套件的 C 與 Python 測試
+web/ 瀏覽器 UI（純 OpenAI API client）
+desktop/ 包裝網頁 UI 的 Tauri v2 桌面 shell
+docs/ 參考文件、實驗與媒體檔
+```
+
+執行階段路徑刻意維持扁平、易讀：`glm.c` 加上少量標頭檔。
+在儲存庫根目錄執行 `make`、`make check` 與 `make clean`，
+都會轉交給引擎的 Makefile。
+
+## 為什麼叫做「colibrì」
+
+蜂鳥只有幾公克重，能在原地懸停，並在一天內造訪上千朵花。
+這套引擎只用蜂鳥般的配給，就能讓 744B 參數的巨人運轉：
+25 GB RAM、十二個 CPU 核心，以及對硬碟的大量耐心。
+
+## 授權條款
+
+Apache 2.0。GLM-5.2 權重由 Z.ai 以 MIT 授權發布。