diff --git a/README.md b/README.md
index 9739507..6b1cbc1 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,19 @@
 # Codex Retry Gateway
 
+- 文档层级：app 项目真源
+- 应用性质：自有 infra 工具
+- 源码来源：git submodule
+- 运行关系：多实例服务
+- 部署模型：managed_systemd_apps
+- 对应服务：`services/pc/systemd-user/codex-retry-gateway/current/README.md`、`services/a100/systemd-user/codex-retry-gateway/current/README.md`
+- 对应 stack：无
+- Secret 边界：本地用户配置
+- 数据来源：本地 Codex provider 配置、gateway profile state 与上游 OpenAI-compatible API 响应。
+- 输出边界：仅返回代理后的 Codex API 响应和本地健康/状态信息。
+- 写入边界：只写本地用户态 gateway 状态目录。
+- 本地状态路径：`~/.codex-retry-gateway/`
+- 备注：token 与 provider secret 只保留在目标用户配置或 secret 文件中，不进入 repo。
+
 一个不依赖 `cc-switch` 路由模式的独立本地网关。
 
 目标：