diff --git a/docs/2026-06-03-CODEGRAPH-INTEGRATION.md b/docs/2026-06-03-CODEGRAPH-INTEGRATION.md
new file mode 100644
index 00000000..986cfbe5
--- /dev/null
+++ b/docs/2026-06-03-CODEGRAPH-INTEGRATION.md
@@ -0,0 +1,91 @@
+# CodeGraph Workspace 接入说明（2026-06-03）
+
+本文档记录本项目如何接入 `/home/long/project` 工作区级 codegraph 搜索基础设施。
+
+## 1. 工作区级入口
+
+所有 agent 共用的 codegraph 使用契约在：
+
+```
+/home/long/project/CODEGRAPH_WORKSPACE_USAGE.md
+```
+
+那份文档是工作区根元文档（**不**在 git 仓库里），包含 16 个 repo 的索引清单、查询路由规则、各 agent 入口、验证方法、能力边界。
+
+## 2. 本项目对 codegraph workspace 的贡献
+
+| 资源              | 状态         | 位置                                                       |
+| ----------------- | ------------ | ---------------------------------------------------------- |
+| CodeGraph 索引    | ✅           | `~/.codegraph/projects.json` 含 `sub2api-cn-relay-manager` |
+| OMP 项目规则      | ✅           | `<repo>/.agent/AGENTS.md`（158 行，2026-06-03 更新）       |
+| 工作区 usage 文档 | ✅（已贡献） | `/home/long/project/CODEGRAPH_WORKSPACE_USAGE.md`          |
+
+## 3. 本项目对其他 agent 的入口信号
+
+其他 agent 第一次进到 `/home/long/project/sub2api-cn-relay-manager` 时，**应该**按以下顺序加载上下文：
+
+1. 仓库根 `AGENTS.md`（60 行）— 项目硬约束 + 质量门禁
+2. `docs/EXECUTION_BOARD.md` — 当前任务执行板
+3. **本文件**（`docs/2026-06-03-CODEGRAPH-INTEGRATION.md`）— 工作区搜索层接入说明
+4. `<repo>/.agent/AGENTS.md`（OMP 专用）— OMP / oh-my-pi 项目级补充规则
+5. `~/.codegraph/projects.json` — 工作区索引状态
+6. `/home/long/project/CODEGRAPH_WORKSPACE_USAGE.md` — 工作区使用契约
+
+## 4. 实际验证（2026-06-03）
+
+```bash
+# 1. 索引存在
+$ grep '"sub2api-cn-relay-manager"' ~/.codegraph/projects.json
+# 命中
+
+# 2. 项目级 OMP 规则存在
+$ ls -l /home/long/project/sub2api-cn-relay-manager/.agent/AGENTS.md
+-rw-rw-r-- 1 long long 9604  6月  3 13:26 AGENTS.md
+
+# 3. codegraph-workspace 能查到本次 frontend 重构的产物
+$ /home/long/.local/bin/codegraph-workspace search sub2api-cn-relay-manager 'portal.css'
+=== sub2api-cn-relay-manager :: /home/long/project/sub2api-cn-relay-manager ===
+/home/long/project/sub2api-cn-relay-manager/docs/EXECUTION_BOARD.md
+/home/long/project/sub2api-cn-relay-manager/deploy/tksea-portal/admin-batch-import.html
+... (命中 deploy/tksea-portal/portal.css 等新文件)
+
+$ /home/long/.local/bin/codegraph-workspace search sub2api-cn-relay-manager 'Sub2ApiPortal'
+=== sub2api-cn-relay-manager :: /home/long/project/sub2api-cn-relay-manager ===
+/home/long/project/sub2api-cn-relay-manager/docs/2026-06-03-FRONTEND-DESIGN-SYSTEM-RUNBOOK.md
+/home/long/project/sub2api-cn-relay-manager/docs/EXECUTION_BOARD.md
+... (命中 deploy/tksea-portal/portal.js 与 runbook 引用)
+
+# 4. def 对 inline JS function 的能力边界（实测）
+$ /home/long/.local/bin/codegraph-workspace def sub2api-cn-relay-manager 'refreshAdminSession'
+===  Finding definitions of: refreshAdminSession
+(空，因为 refreshAdminSession 在 HTML inline <script> 里)
+# → 印证 skill 文档：inline JS function 走 search_files fallback，而不是 def
+```
+
+## 5. OMP 可发现性 — 当前限制
+
+按 `codegraph-workspace-operations` skill 的标准做法，新写 `.agent/AGENTS.md` 后应该用：
+
+```bash
+OMP_NO_UPDATE_NOTIFIER=1 omp -p --cwd /home/long/project/sub2api-cn-relay-manager \
+  "show me your current project rules"
+```
+
+**本机当前实测（2026-06-03）**: OMP 返回 `403 余额不足`，验证不可用。
+
+代替证据：
+
+1. 物理文件存在（`ls -l .agent/AGENTS.md`）
+2. `~/.codegraph/projects.json` `has_agents: true`
+3. `codegraph-workspace search` 能命中项目内容
+
+OMP quota 恢复后请补一次实测并把结果记到本文件第 4 节。
+
+## 6. 后续维护
+
+- 本项目新增/重构时：
+  1. 在 `docs/EXECUTION_BOARD.md` 加条目
+  2. 若有 .agent/AGENTS.md 引用过的真相文件，**同步更新** .agent/AGENTS.md
+  3. 跑 `codegraph-workspace refresh sub2api-cn-relay-manager` 让索引反映新代码
+- OMP quota 恢复后立即补上第 5 节的实测
+- 任何本项目接入 codegraph workspace 的规则变更，先在 `/home/long/project/CODEGRAPH_WORKSPACE_USAGE.md` 改，再回本文件