diff --git a/docs/reference/opencode-integration.md b/docs/reference/opencode-integration.md
index 10e3d10e..8925efe6 100644
--- a/docs/reference/opencode-integration.md
+++ b/docs/reference/opencode-integration.md
@@ -15,6 +15,14 @@
 - `hwlab_opencode_ticket` 只用于 OpenCode iframe 首跳和后续代理 cookie 绑定；日志、issue、probe 报告和命令输出只能记录 ticket presence、redacted URL 或 fingerprint，不能打印 ticket 值。
 - OpenCode proxy 在没有有效 HWLAB session、ticket 缺失、ticket 过期或 upstream 配置缺失时必须返回结构化 JSON，并由 Cloud Web 页面展示受控状态；不得让裸 JSON 成为 `/opencode` 主入口的用户体验。
 
+## 默认 project 与 session 列表
+
+- HWLAB 的 OpenCode 默认工作区由 Cloud Web runtime 配置进入运行面。OpenCode 左侧 session 列表依赖浏览器端 OpenCode project store 能看到 `/workspace`；如果只把 iframe 路由带到 `/workspace/session`，但没有让 OpenCode 前端 store 打开该 project，左侧仍可能表现为空 project 或只剩 `Load more`。
+- 默认 project bootstrap 必须满足 OpenCode 上游 CSP。不要向 OpenCode HTML 注入 inline `localStorage` script；Cloud Web 应提供同源外部脚本资源，并由 HTML 只引用 `script-src 'self'` 允许的 `src`。
+- Cloud Web 代理改写 OpenCode HTML 时，如果通过运行时 `fetch()` 读取 upstream body，必须按已解码/已重写的新 body 重建实体 header。至少不得继续透传 upstream 的 `content-encoding`、`content-md5` 和 `etag`；`content-length` 以改写后 body 为准。
+- Web 验收不要只看 OpenCode `/project` API。最终口径应从用户入口 `/opencode` 验证 iframe 自然进入 `/workspace` 相关 route，OpenCode browser storage 中 project store 包含 `/workspace`，左侧 DOM 出现真实 session 节点或标题，且页面没有 `No projects open` / `Open a project to get started`。
+- 临时 probe 可以读取 storage/API 帮助定位，但不得把手工写 localStorage、点击 Recent project 或 reload repair 当成通过条件；这些只能作为 P2 方向验证，不能替代用户入口自然收敛。
+
 ## OTel 可追踪性
 
 - OpenCode frame-url 和 proxy 拒绝分支必须返回 `traceparent`、`x-hwlab-otel-trace-id`、`x-request-id`，响应 body 的 diagnostic 可以包含同一组 id 和 `valuesPrinted=false`。