diff --git a/CLAUDE.md b/CLAUDE.md
index 42b889b..6abfb39 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,13 +12,22 @@ YaYa is a calendar app built with Kotlin Multiplatform (KMP) + Compose Multiplat
 # Build Android debug APK
 ./gradlew :androidApp:assembleDebug
 
-# Run shared module tests
+# Install Android debug APK to connected device
+./gradlew :androidApp:installDebug
+
+# Run all shared module tests
+./gradlew :shared:allTests
+
+# Run shared module tests on Android host only
 ./gradlew :shared:testAndroidHostTest
 
 # Run a single test class
 ./gradlew :shared:testAndroidHostTest --tests "plus.rua.project.ui.CalendarUtilsTest"
 
-# Build iOS app — open iosApp/ in Xcode and run from there
+# Generate iOS framework (required before first Xcode open or after clean)
+./gradlew :shared:generateDummyFramework
+
+# Build iOS app — open iosApp/iosApp.xcworkspace in Xcode and run from there
 ```
 
 Gradle configuration cache and build cache are enabled by default (`gradle.properties`).
@@ -62,13 +71,17 @@ CalendarMonthView          ← top-level screen (MonthHeader + WeekdayHeader + p
 
 `CalendarViewModel` holds `selectedDate` and `isCollapsed` state, computes month day grids (6×7=42 cells) and ISO week numbers. Week starts on Monday (ISO 8601).
 
+**Performance tracing:** `ComposeTrace.kt` provides `composeTraceBeginSection`/`composeTraceEndSection` via expect/actual — Android routes to `android.os.Trace`, iOS is a no-op. Custom markers are inserted at key points (e.g., `MonthView:Compose`, `YearView:Compose`, `VM:collapseProgress`) for Perfetto/Systrace analysis. See `DEVELOPMENT.md` for trace recording and Python parsing scripts.
+
 ## Key Dependencies
 
 - Kotlin 2.3.21, Compose Multiplatform 1.11.0, Material 3 1.10.0-alpha05
 - `kotlinx-datetime` 0.8.0 for all date logic (no java.util.Calendar)
 - `tyme4kt` for Chinese traditional calendar (lunar dates, solar terms, festivals)
+- `sketch` 4.4.0 for animated GIF display (`AsyncImage` with `sketch-animated-gif`)
 - AGP 9.2.1, compileSdk/targetSdk 37, minSdk 24
 - JVM target: 17
+- R8 full mode enabled (`android.enableR8.fullMode=true`)
 
 ## Conventions
 
diff --git a/README.md b/README.md
index 1adebe9..54e0f8b 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,20 @@
 # YaYa
 
-基于 Kotlin Multiplatform 与 Compose Multiplatform 的日历应用，Android 和 iOS 共享 UI。
+基于 Kotlin Multiplatform 与 Compose Multiplatform 的跨平台日历应用,Android 与 iOS 共享同一套 UI 与业务逻辑。
 
-月视图与周视图之间支持流畅的折叠/展开过渡——拖拽切换，弹簧动画自动吸附。无限分页，ISO 8601 周起始，Material 3。
+## 特性
 
-## 构建
-
-```bash
-# Android
-./gradlew :androidApp:assembleDebug
-
-# iOS — 在 Xcode 中打开 iosApp/ 运行
-```
+- **流畅的视图切换** —— 月视图、周视图、年视图三种模式,拖拽手势驱动月↔周折叠,弹簧动画自动吸附
+- **无限滑动分页** —— 基于 `Int.MAX_VALUE` 的虚拟分页,前后无边界翻页
+- **完整中式日历** —— 公历 + 农历 + 二十四节气 + 传统节日,ISO 8601 周起始(周一)
+- **个人排班周期** —— 自定义工作/休息循环,与公共节假日独立
+- **Material 3 设计** —— 动态配色,深色模式
 
 ## 技术栈
 
-- Kotlin 2.3 · Compose Multiplatform 1.10 · Material 3
+- Kotlin 2.3 · Compose Multiplatform 1.11 · Material 3
 - `kotlinx-datetime` 处理所有日期逻辑
-- 双模块：`:shared`（UI + 逻辑）· `:androidApp`（薄壳）
+- `tyme4kt` 提供农历、节气与传统节日
+- `sketch` 渲染 GIF 动画
+- 双模块:`:shared`(UI + 逻辑) · `:androidApp`(薄壳)
+- iOS 入口为 `MainViewController.kt`,Xcode 工程位于 `iosApp/`