diff --git a/internal/transport/http/docs/openapi.yaml b/internal/transport/http/docs/openapi.yaml
index 6820fb6..131cda1 100644
--- a/internal/transport/http/docs/openapi.yaml
+++ b/internal/transport/http/docs/openapi.yaml
@@ -335,6 +335,100 @@ info:
     本机 TCP 把 Host/Port 换成 `127.0.0.1:8090`，并用 **明文 TCP**（不要 TLS）。HTTP 仍用 `http://127.0.0.1:8080`。
 
     仓库可运行示例：`docs/clients/SparkImClient.java`、`docs/clients/SparkImClient.swift`。
+
+    ---
+
+    ## 客户端页面跳转
+
+    这一节是当前 iOS 客户端的页面导航，不是新接口。不要据此发明或调用本规范未列出的 HTTP / TCP 命令。底部实际是四个 Tab：消息、广场、匹配、我的。「发现」是广场里的分段，不是第五个底栏。返回用侧滑或返回键，弹窗用关闭，大图和「我的」侧栏盖在当前页上。这是客户端导航，工作区后续改动可能使它过时。
+
+    主路径：
+
+    ```mermaid
+    flowchart TD
+     start["启动"] -->|替换根| login["邮箱登录"]
+     start -->|已登录 替换根| home["主页"]
+     start -->|封禁中 替换根| ban["违规页"]
+     login -->|push| code["邮箱验证码"]
+     login -->|present| agree["用户协议 / 隐私政策"]
+     login -->|push| fb["意见反馈"]
+     login -->|同页切换| pwd["密码登录"]
+     code -->|替换根| home
+     pwd -->|替换根| home
+     code -->|返回| login
+     home -->|tab| msg["消息"]
+     home -->|tab| square["广场"]
+     home -->|tab| match["匹配"]
+     home -->|tab| me["我的"]
+     msg -->|push| single["单聊"]
+     msg -->|push| group["群聊"]
+     msg -->|push| sys["系统消息"]
+     msg -->|push| contacts["通讯录"]
+     msg -->|push| add["添加朋友"]
+     single -->|push| detail["聊天详情"]
+     single -->|覆盖层| preview["图片与视频大图"]
+     single -->|push| video["视频播放"]
+     group -->|push| gset["群设置"]
+     contacts -->|push| profile["好友资料"]
+     profile -->|push| single
+     square -->|分段| follow["关注"]
+     square -->|分段| discover["发现"]
+     square -->|push| publish["发布动态"]
+     follow -->|push| post["动态详情"]
+     discover -->|push| post
+     follow -->|push| homePage["广场个人主页"]
+     discover -->|push| homePage
+     match -->|资料已齐 tab| card["卡片匹配"]
+     match -->|资料未齐 tab| fill["资料填写"]
+     fill -->|push| card
+     card -->|push| cardInfo["名片详情"]
+     me -->|覆盖层| drawer["我的侧栏"]
+     drawer -->|push| setting["设置"]
+     me -->|push| myProfile["个人资料"]
+    ```
+
+    设置与账号：
+
+    ```mermaid
+    flowchart TD
+     setting["设置"] -->|push| account["账号与安全"]
+     setting -->|push| teen["青少年模式"]
+     setting -->|push| myProfile["个人资料"]
+     setting -->|push| notice["消息通知"]
+     setting -->|push| chatSet["聊天"]
+     setting -->|push| privacy["隐私"]
+     setting -->|push| general["通用"]
+     setting -->|push| help["帮助"]
+     setting -->|push| feedback["意见反馈"]
+     setting -->|push| about["关于我们"]
+     account -->|push| bind["第三方账号绑定"]
+     account -->|push| real["实名认证"]
+     account -->|push| resetPwd["设置或重置登录密码"]
+     account -->|push| secPwd["安全密码"]
+     account -->|push| cancel["账号注销"]
+     myProfile -->|present| avatarCrop["头像裁切"]
+     myProfile -->|push| qr["我的二维码"]
+    ```
+
+    图片预览与编辑。编辑含涂鸦、贴图、文字、裁剪、马赛克。头像只有裁切。
+
+    ```mermaid
+    flowchart TD
+     chat["单聊或群聊"] -->|覆盖层| browser["图片与视频大图"]
+     chat -->|push| player["视频播放"]
+     chat -->|present| album["相册"]
+     chat -->|push| albumPreview["相册预览"]
+     browser -->|present| editor["图片编辑"]
+     album -->|present| editor
+     profile["个人资料"] -->|present| cropOnly["头像裁切"]
+     editor -->|同页| doodle["涂鸦"]
+     editor -->|同页| sticker["贴图"]
+     editor -->|覆盖层| text["文字"]
+     editor -->|同页| clip["裁剪"]
+     editor -->|同页| mosaic["马赛克"]
+    ```
+
+    消息右上角还能进添加朋友、扫一扫、发起群聊和群发助手。系统消息进意见反馈。单聊详情进好友资料、查找记录、投诉和会话锁定。侧栏里「附近的人」和「我的钱包」当前点不到。语音通话在菜单里已被注释。这些同样只是客户端导航。
 servers:
   - url: https://sparkapi.wyrs365.com
     description: 生产（IM / 音乐客户端）