From dc9697bf3d029b94a50a8dd999f163daf415e3b3 Mon Sep 17 00:00:00 2001
From: Rocky <rocky.hk@gmail.com>
Date: Wed, 24 Jun 2026 17:06:45 +0800
Subject: [PATCH] =?UTF-8?q?docs(zh):=20=E5=90=8C=E6=AD=A5=20banner=20?=
 =?UTF-8?q?=E5=92=8C=20XcodeGen=20=E6=9E=84=E5=BB=BA=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=E5=88=B0=E4=B8=AD=E6=96=87=20README?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.zh.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/README.zh.md b/README.zh.md
index 54bd70e..a112bdf 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -11,6 +11,60 @@
 
 ---
 
+> ⚠️ **2026-06-24**: Default branch renamed from `main` to `0.2`. Old `main` is now `0.1`; `refactor/drop-qwen3-coreml` is now `0.2`. See CHANGELOG for details.
+
+## Build Setup
+
+This project uses [XcodeGen](https://github.com/yonaskolb/XcodeGen) — `project.yml`
+is the source of truth, and `OSGKeyboard.xcodeproj` is **regenerated, not committed**
+(it's in `.gitignore`). New clones must generate the Xcode project before opening
+in Xcode, otherwise Xcode will show an empty project with no source files.
+
+### Prerequisites
+
+- macOS with **Xcode 26** (matches `project.yml` deployment target iOS 26)
+- [Homebrew](https://brew.sh)
+
+### One-time setup
+
+```bash
+brew install xcodegen
+```
+
+### Generate `OSGKeyboard.xcodeproj`
+
+From the repository root:
+
+```bash
+./Scripts/generate-xcodeproj.sh
+```
+
+This script:
+
+1. Runs `xcodegen generate` to produce `OSGKeyboard.xcodeproj` from `project.yml`.
+2. Calls `Scripts/patch-icon-composer.sh` to patch the generated project for
+   Xcode 26 Icon Composer bundles — `OSGKeyboard/AppIcon.icon` is treated as
+   a single `folder.iconcomposer.icon` reference (see `project.yml` note on
+   XcodeGen `fileTypes.icon`).
+
+Then open the project:
+
+```bash
+open OSGKeyboard.xcodeproj
+```
+
+> **Troubleshooting**: If Xcode shows an empty project, re-run
+> `./Scripts/generate-xcodeproj.sh`. If the build fails on icon assets,
+> make sure `OSGKeyboard/AppIcon.icon/` exists with `Assets/` and `icon.json`
+> inside (do not expand the folder manually).
+
+### Re-running
+
+Run `./Scripts/generate-xcodeproj.sh` any time `project.yml` changes
+(e.g. after `git pull`).
+
+---
+
 ## 这是什么？
 
 OSGKeyboard 是商业语音输入工具的免费、源码可见替代方案。它以 **iOS 自定义键盘扩展** 的形式运行，所以你可以在 **任何 App** 里使用 —— 微信、备忘录、邮件、ChatGPT、Claude、Cursor，无所不能。