diff --git a/docs/guide.md b/docs/guide.md
index 5d66bb5..bb0cdaa 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -577,3 +577,33 @@ useDict(code)  // → { items, tagMap, options }，均响应式
 | 首登登录后所有接口 403 | `must_change_password=true`，需先改密：仅 `PATCH /auth/me/password` 放行，前端会强制跳改密页 |
 | 强退后 token 仍短暂可用 | access 最长 2h 内失效（sid 黑名单）；refresh 已被吊销无法续期 |
 | 切页签数据没保留 | 该页声明了 `meta.keepAlive:false`，或页面缺 `defineOptions({ name })` 导致缓存标识失效 |
+
+---
+
+## 8. 升级与定制（fork 后如何同步上游）
+
+脚手架是「通用底座」，fork 成具体项目后，**业务代码和脚手架代码必须物理分离**，才能在上游升级时干净合并。
+
+### 8.1 升级同步（git upstream + merge）
+
+```bash
+git clone <脚手架地址> my-project
+cd my-project
+git remote rename origin upstream            # 脚手架 = upstream
+git remote add origin <我的业务仓库地址>      # 业务 = origin
+# 日常在 main 上开发业务，升级时：
+git fetch upstream
+git merge upstream/main                       # 冲突只在「你改过脚手架文件」的地方出现
+```
+
+- 业务代码**纯新增**（新模块/新页面/新资源）→ 升级几乎零冲突。
+- 业务代码**改了脚手架文件** → 上游升级该文件即冲突，改得越深越痛。
+- 将来项目变多、需要版本语义时，再评估把脚手架抽成 npm 包 / monorepo 依赖（彻底隔离、按版本升级）。
+
+### 8.2 可定制面（三条铁律）
+
+| 铁律 | 说明 |
+|---|---|
+| **框架代码只读** | 脚手架自带模块/页面/服务（`users`/`roles`/`system/*`/`common/*`/`ty-*`…）只读不改 |
+| **业务代码落点** | 新增放独立业务目录：后端新域 `src/<domain>/`，前端新页面 `src/pages/<biz>/`，不侵入框架目录 |
+| **定制走扩展点** | 外观/权限优先走数据驱动扩展点：租户品牌（`tenant.brand_*`）、字典、主题色、资源注册（`tenant-template.ts` + `pnpm sync:resources`），而非改源码 |
diff --git a/openspec/changes/archive/2026-10-11-customization-surface/.openspec.yaml b/openspec/changes/archive/2026-10-11-customization-surface/.openspec.yaml
new file mode 100644
index 0000000..a369219
--- /dev/null
+++ b/openspec/changes/archive/2026-10-11-customization-surface/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-11
diff --git a/openspec/changes/archive/2026-10-11-customization-surface/proposal.md b/openspec/changes/archive/2026-10-11-customization-surface/proposal.md
new file mode 100644
index 0000000..8b2b086
--- /dev/null
+++ b/openspec/changes/archive/2026-10-11-customization-surface/proposal.md
@@ -0,0 +1,18 @@
+## Why
+
+fork 后项目与脚手架之间没有清晰的「可定制面」约定，业务代码容易混入框架目录，导致上游升级时 merge 冲突频繁、无法干净同步。需要把「框架只读 / 业务落点 / 数据驱动扩展点」固化为 spec，作为 fork 升级的契约。
+
+## What Changes
+
+- `shared/platform` 新增「脚手架可定制面」需求：三条铁律（框架代码只读、业务代码独立落点、定制走扩展点）。
+- `docs/guide.md` 补「升级同步（git upstream + merge）+ 可定制面」章节。
+
+## Capabilities
+
+### Modified Capabilities
+
+- `shared/platform`: 新增「脚手架可定制面」约定。
+
+## Impact
+
+- 无代码变更；仅 spec + 文档。
diff --git a/openspec/changes/archive/2026-10-11-customization-surface/specs/shared/platform/spec.md b/openspec/changes/archive/2026-10-11-customization-surface/specs/shared/platform/spec.md
new file mode 100644
index 0000000..f3cec92
--- /dev/null
+++ b/openspec/changes/archive/2026-10-11-customization-surface/specs/shared/platform/spec.md
@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: 脚手架可定制面
+脚手架 SHALL 为 fork 项目划定「可定制面」：框架自带模块/页面/服务为框架代码，fork 项目只读不改；业务新增代码落入独立业务目录，与框架目录分离，保证上游升级可经 git merge 干净同步。
+
+#### Scenario: 框架代码只读
+- **WHEN** fork 项目需要扩展能力
+- **THEN** 不修改框架自带模块/页面/服务，而是新增业务模块/页面或经扩展点定制
+
+#### Scenario: 业务代码落点
+- **WHEN** fork 项目新增业务
+- **THEN** 代码落入独立业务目录（后端新域 `src/<domain>/`、前端新页面 `src/pages/<biz>/`），不侵入框架目录
+
+#### Scenario: 数据驱动扩展点
+- **WHEN** fork 项目需要定制外观或权限
+- **THEN** 优先经数据驱动扩展点（租户品牌、字典、主题色、资源注册 tenant-template）而非改源码
diff --git a/openspec/changes/archive/2026-10-11-customization-surface/tasks.md b/openspec/changes/archive/2026-10-11-customization-surface/tasks.md
new file mode 100644
index 0000000..5fa5d53
--- /dev/null
+++ b/openspec/changes/archive/2026-10-11-customization-surface/tasks.md
@@ -0,0 +1,5 @@
+## 1. Spec 与文档
+
+- [x] 1.1 主 spec `shared/platform` 新增「脚手架可定制面」需求
+- [x] 1.2 `docs/guide.md` 补「升级同步 + 可定制面」章节
+- [x] 1.3 `openspec validate` 通过
diff --git a/openspec/specs/shared/platform/spec.md b/openspec/specs/shared/platform/spec.md
index 5dde1cd..b01e35e 100644
--- a/openspec/specs/shared/platform/spec.md
+++ b/openspec/specs/shared/platform/spec.md
@@ -37,3 +37,18 @@
 #### Scenario: 日志脱敏
 - **WHEN** 记录操作/登录日志
 - **THEN** 密码字段不落日志，手机号/邮箱部分打码
+
+### Requirement: 脚手架可定制面
+脚手架 SHALL 为 fork 项目划定「可定制面」：框架自带模块/页面/服务为框架代码，fork 项目只读不改；业务新增代码落入独立业务目录，与框架目录分离，保证上游升级可经 git merge 干净同步。
+
+#### Scenario: 框架代码只读
+- **WHEN** fork 项目需要扩展能力
+- **THEN** 不修改框架自带模块/页面/服务，而是新增业务模块/页面或经扩展点定制
+
+#### Scenario: 业务代码落点
+- **WHEN** fork 项目新增业务
+- **THEN** 代码落入独立业务目录（后端新域 `src/<domain>/`、前端新页面 `src/pages/<biz>/`），不侵入框架目录
+
+#### Scenario: 数据驱动扩展点
+- **WHEN** fork 项目需要定制外观或权限
+- **THEN** 优先经数据驱动扩展点（租户品牌、字典、主题色、资源注册 tenant-template）而非改源码