diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md
index de2ea8e9..ef7cd97c 100644
--- a/docs/reference/hwlab.md
+++ b/docs/reference/hwlab.md
@@ -113,6 +113,12 @@ Cloud Web runtime config 或 YAML-first UI policy 类修复关闭前，除源码
 
 Workbench prompt、TraceTimeline、final response、详情弹窗、session 切换、deep link 和运行态一致性问题的浏览器证据要求统一见 `$unidesk-webdev`；typed CLI 交叉验证仍见 `$hwlab-code-agent`。这里不再复制 selector、fresh context、turn authority 或登录排障细则，避免与 WebDev 操作面产生多路径。
 
+### OpenCode 独立 UI 入口
+
+HWLAB 接入 OpenCode 时，默认采用独立 `opencode-server` Pod 和独立 public hostname，通过 Cloud Web 的 `/opencode` 导航与 iframe 集成；不要把 OpenCode UI 与 HWLAB Cloud Web 合并到同一个 Pod，也不要让 public OpenCode hostname 直接暴露 OpenCode Basic Auth。Cloud Web 继续拥有 HWLAB 登录态和同源 session，OpenCode public hostname 应先经过 Cloud Web 鉴权代理；未登录访问 OpenCode host 的健康或 API 路径时，预期是 Cloud Web 的鉴权失败响应，而不是浏览器 Basic Auth 弹窗。
+
+OpenCode provider/model、public hostname、SecretRef 和 extra FRP proxy 都必须从 issue/CLI 选中的 node/lane YAML 与目标 HWLAB repo render 读取；长期参考不硬编码当前模型或端口。关闭 OpenCode 集成、provider profile 或微前端入口类 issue 时，最小证据应来自选中 node/lane 的 `web-probe script`：登录 HWLAB public origin，打开 `/opencode`，确认 iframe origin、OpenCode `/global/health`、`/config` 中的 provider/model、`/session` 创建，以及 `/session/:id/message` 返回的 providerID、modelID、terminal finish 和最终 assistant text。只看到 `opencode-server` Pod ready、Caddy hostname 200 或 Secret 存在，不能替代这个浏览器入口 smoke。
+
 ## HWLAB FRP 维护
 
 HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担，容器使用 host network，并把 `/opt/hwlab-frp/frps.dev.toml` 只读挂载到 `/etc/frp/frps.toml`。这个 server 侧 allowlist 是 UniDesk 指挥侧维护对象，不属于 G14 k3s GitOps desired state；G14 侧 `frpc` ConfigMap/Deployment 只负责各 runtime namespace 的客户端 tunnel。
@@ -123,6 +129,8 @@ HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担
 
 FRP 维护验证顺序是：确认 `hwlab-frps-dev` 或 `config/hwlab-node-lanes.yaml` 指定的 publicExposure 入口仍挂载/渲染目标配置；重启或 apply 后用等价只读命令确认 FRP/Caddy 正在监听目标公网端口或 hostname；再在目标 namespace 查看 `frpc` 日志，确认对应 proxy `start proxy success`；最后验证选中 node/lane 的 active runtime 入口。D601 `v0.3` 验证使用 `https://hwlab.pikapython.com`；其他 node/lane 使用 YAML 中的 public URL。
 
+当 public URL 返回 404/502 或 Caddy local probe 失败时，不要只凭某个历史端口、旧 worktree YAML 或当前 Caddyfile 猜测修复方向。先对齐三层事实：UniDesk `config/hwlab-node-lanes.yaml` 的 publicExposure、目标 runtime GitOps/ConfigMap 渲染出的 `frpc` 配置、以及 PK01 loopback 对每个 FRP remote port 的真实响应；同时查看 `frpc` 日志中对应 proxy 是 `start proxy success`、`port already used` 还是 `port not allowed`。Caddy 主站的 API 路径应指向 edge-proxy，上层 Web/auth/OpenCode iframe 路径应由 Cloud Web 处理；若三层事实不一致，先修拥有该事实的 YAML/source，再用受控 public-exposure 或 GitOps render 收敛，不能手工把 Caddy 临时指向看似可用的旧端口。
+
 FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Secret 对象/key 是否存在和健康摘要；不得记录 Secret value、provider token、完整 DB URL、Codex auth JSON 或其他凭据内容。
 
 ## 门禁最小化与扩容治理
diff --git a/docs/reference/platform-infra.md b/docs/reference/platform-infra.md
index 5b0d81be..dd894f51 100644
--- a/docs/reference/platform-infra.md
+++ b/docs/reference/platform-infra.md
@@ -203,6 +203,8 @@ PK01 `/etc/caddy/Caddyfile` is a shared edge artifact for multiple YAML owners,
 
 Do not render and install a whole PK01 Caddyfile from a single service YAML. Sub2API, LangBot, n8n, HWLAB and future public services must coexist by distinct `# BEGIN unidesk managed <owner>` blocks. When the same service exposes multiple public targets at once, the Caddy owner must be target-scoped unless an existing legacy owner is intentionally preserved for backward compatibility; for Sub2API, D601 keeps the legacy `sub2api` block and non-default targets use owners such as `sub2api-d518`. A public exposure closeout should verify the service's own public URL and, when the operation touched PK01 Caddy, confirm that unrelated managed blocks are still present or that the apply output reports they were preserved.
 
+When one Caddy site has both path-specific upstreams and a catch-all upstream, render the path routes inside `handle @matcher { ... }` blocks and put the default upstream in a final `handle { ... }` block. Do not rely on `reverse_proxy @matcher ...` followed by an unqualified `reverse_proxy ...`: the catch-all route can still capture matcher paths after Caddy adapts the file. Validation must include both `caddy adapt`/`validate` and loopback HTTPS or local-port probes for at least one matcher path and one catch-all path; if a matcher path returns the catch-all service's response, treat it as an edge routing bug rather than an application health failure.
+
 ## Availability And Probes
 
 Kubernetes readiness is not the same as pool availability: