diff --git a/README.md b/README.md
index 6a3f103..49fe212 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,20 @@
 # codex-retry-gateway-tui
 
+- 文档层级：客户端工具
+- 应用性质：客户端 TUI
+- 源码来源：git submodule
+- 运行关系：客户端工具
+- 部署模型：外部安装器
+- 对应服务：`services/pc/user-app/codex-retry-gateway-tui/current/README.md`、`services/a100/user-app/codex-retry-gateway-tui/current/README.md`
+- 对应 stack：无
+- Secret 边界：本地用户配置
+- 分发方式：`uvx` / `uv tool install`。
+- 包名：`codex-retry-gateway-tui`
+- 命令名：`codex-retry-gateway-tui`
+- 本地状态路径：`~/.config/codex-retry-gateway-tui/`
+- 目标 API：本机或内网 codex-retry-gateway。
+- 备注：客户端工具本身不是长期服务；user-app README 只记录具体宿主安装状态。
+
 Terminal UI for `codex-retry-gateway`.
 
 ## Quick Start