diff --git a/README.md b/README.md
index 574b650..5881221 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,123 @@
-# sunny_mochi
+# sunny_mochi — Flutter 企业级脚手架
 
-A new Flutter project.
+基于 Flutter 3.x 的企业级 APP 脚手架，开箱即用的基础设施底座。
 
-## Getting Started
+## 包含能力
 
-This project is a starting point for a Flutter application.
+| 模块 | 说明 |
+|------|------|
+| Flavor 三包 | dev / staging / prod 环境共存 |
+| 加密数据库 | Drift + SQLCipher AES-256 |
+| 网络层 | 7 拦截器 Dio（Token 刷新互斥、证书绑定、错误映射） |
+| 崩溃日志 | 同步写文件 + 启动时弹窗上报 |
+| 错误分类 | Sealed Failure 体系（Network / Auth / Server / Cache） |
+| 主题系统 | 5 套色板 + 深色模式 + Riverpod 持久化 |
+| 开发者面板 | Talker UI（Internal 包可见，Release 编译期关闭） |
+| 认证骨架 | Clean Architecture：手机号 + 短信 / 密码双模式登录 |
+| 本地错误日志 | 查看 + 一键上报 |
+| i18n | Slang 4.x（zh-CN 基准 + en 备用） |
 
-A few resources to get you started if this is your first Flutter project:
+---
 
-- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
-- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
+## 克隆后首次设置
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+### 1. 安装依赖
+```bash
+flutter pub get
+```
+
+### 2. 代码生成
+```bash
+make gen        # build_runner → .g.dart / .freezed.dart
+make gen-i18n   # slang → lib/i18n/strings.g.dart
+```
+
+### 3. 填入项目 API 路径
+编辑 `lib/core/config/api_paths.dart`，将所有空字符串替换为实际路径。
+
+### 4. 配置 Android 签名（发布版必须）
+```bash
+cp android/key.properties.template android/key.properties
+# 编辑 key.properties，填入 keystore 路径和密码
+```
+
+### 5. 配置生产环境变量
+```bash
+cp dart-defines/prod.json.template dart-defines/prod.json
+# 编辑 prod.json，填入 Sentry DSN、RSA 公钥等
+```
+
+### 6. iOS（首次或 Pod 变更后）
+```bash
+cd ios && pod install && cd ..
+```
+
+---
+
+## 常用命令
+
+```bash
+make run-dev        # 开发版调试运行
+make run-staging    # 测试版 Release 运行
+make build-staging  # 打测试包 APK
+make build-prod     # 打正式版 AAB（需先配置 prod.json + key.properties）
+make gen            # 代码生成
+make gen-i18n       # i18n 生成
+flutter analyze     # 静态分析（目标 0 errors）
+flutter test        # 单元测试
+```
+
+---
+
+## 新项目初始化清单
+
+- [ ] 替换包名 `com.example.sunny_mochi` → 项目包名（`android/app/build.gradle.kts` + `pubspec.yaml`）
+- [ ] 填入 API 路径（`lib/core/config/api_paths.dart`）
+- [ ] 配置 `android/key.properties`（从 `key.properties.template` 复制）
+- [ ] 配置 `dart-defines/prod.json`（从 `prod.json.template` 复制）
+- [ ] 替换 App 名称（`android/app/build.gradle.kts` `resValue`、`ios/Runner/Info.plist`）
+- [ ] 替换 App Icon（`android/app/src/main/res/mipmap-*/`、`ios/Runner/Assets.xcassets/AppIcon.appiconset/`）
+- [ ] 实现 Tab 页面（替换 `lib/core/router/routes.dart` 中的 placeholder build）
+- [ ] 添加业务路由（`lib/core/router/routes.dart` 新增 `@TypedGoRoute`）
+- [ ] 配置 Sentry DSN（`dart-defines/prod.json`）
+- [ ] 配置 RSA 公钥（`dart-defines/dev.json`、`staging.json`、`prod.json`）
+
+---
+
+## 项目结构
+
+```
+lib/
+├── main.dart               # 6 步启动序列
+├── app.dart                # AppRoot → MaterialApp.router
+├── i18n/                   # Slang 翻译
+├── core/
+│   ├── config/             # Env / ApiConfig / ApiPaths（填入 API 路径）
+│   ├── router/             # GoRouter + TypedRoutes（添加业务路由）
+│   ├── network/            # Dio 7 拦截器 + MockAdapter
+│   ├── storage/            # Drift + SQLCipher + SecureStorage
+│   ├── crash/              # CrashReporter 生命周期
+│   ├── error/              # Sealed Failure 分类
+│   ├── theme/              # 5 色板 + 深色模式
+│   ├── observability/      # Talker + Sentry
+│   ├── sync/               # Offline-First 同步框架骨架
+│   ├── crypto/             # RSA 加密
+│   ├── extensions/         # BuildContext / String / num / DateTime
+│   ├── utils/              # 验证器 / 密码强度 / SMS 倒计时
+│   └── widgets/            # 通用 UI 组件库
+└── features/
+    ├── auth/               # 认证（完整 Clean Architecture，替换登录 UI 品牌）
+    ├── dev_panel/          # Talker 调试面板（Internal 包）
+    └── error_report/       # 本地错误日志 + 上报
+
+android/
+├── app/build.gradle.kts    # Flavor 三包 + SQLCipher + 签名配置
+├── key.properties.template # 签名配置模板（复制为 key.properties 并填入密码）
+└── keystore/               # 放置 .jks 文件（.gitignore 中，勿提交）
+
+dart-defines/
+├── dev.json                # 开发环境变量（占位符，可提交）
+├── staging.json            # 测试环境变量（占位符，可提交）
+├── prod.json.template      # 生产环境变量模板
+└── prod.json               # 生产真实配置（.gitignore 中，勿提交）
+```
diff --git a/android/key.properties.template b/android/key.properties.template
new file mode 100644
index 0000000..2d57ab3
--- /dev/null
+++ b/android/key.properties.template
@@ -0,0 +1,20 @@
+# Android 签名配置
+#
+# 使用步骤：
+#   1. 将此文件复制为 key.properties（与 build.gradle.kts 同级，即 android/ 目录）
+#   2. 填入真实密钥信息
+#   3. key.properties 已在 .gitignore 中，不会被提交（CI/CD 通过 secret 注入）
+#
+# 生成新 keystore（如果没有）：
+#   keytool -genkey -v -keystore release.jks \
+#     -alias your-key-alias -keyalg RSA -keysize 2048 -validity 10000
+#
+# 注意：
+#   - storeFile 路径相对于 android/app/ 目录
+#   - 建议把 .jks 放在 android/keystore/（已在 .gitignore 中）
+#   - 妥善保管 keystore 文件，丢失后无法更新已发布 APP
+
+storePassword=YOUR_KEYSTORE_PASSWORD
+keyPassword=YOUR_KEY_PASSWORD
+keyAlias=YOUR_KEY_ALIAS
+storeFile=../keystore/release.jks