diff --git a/.agents/skills/unidesk-sub2api/references/operations.md b/.agents/skills/unidesk-sub2api/references/operations.md
index 23f8d2cd..fa9bd4db 100644
--- a/.agents/skills/unidesk-sub2api/references/operations.md
+++ b/.agents/skills/unidesk-sub2api/references/operations.md
@@ -83,10 +83,12 @@ proxy secret/config 文件只允许放在受控 Secret/state 路径，输出只
 
 ## 镜像升级
 
-1. 修改 `config/platform-infra/sub2api.yaml` 的 `image.repository`、`image.tag` 或 `pullPolicy`。
-2. 执行 `sub2api plan`，确认策略检查通过。
-3. 执行 `sub2api apply --confirm`，轮询 job 完成。
-4. 执行 `sub2api status`，确认运行镜像等于 YAML 声明。
-5. 执行 `sub2api validate` 或 `codex-pool validate` 做入口验收。
+1. 先定位目标 target 的 `id`、`publicBaseUrl` 和当前 `image` block。`config/platform-infra/sub2api.yaml` 同时有全局默认镜像和多个 target-scoped 镜像；只升级单个 target 时必须用 `id: <target>` 附近的上下文 patch，不能按第一个 `tag:` 命中。
+2. 只修改目标 target 的 `image.repository`、`image.tag` 或 `pullPolicy`；不要顺手改全局默认、PK01 host-Docker target、standby target 或其它共用 `api2.pikapython.com` 历史 target。
+3. 提交前用 `git diff -- config/platform-infra/sub2api.yaml` 和 `rg -n "id: <target>|tag: <version>|publicBaseUrl"` 确认只有目标 target 变化，且要保护的公开入口没有被误改。
+4. 执行 `sub2api plan --target <target>` 和 `sub2api apply --target <target> --dry-run`，确认策略检查通过。
+5. 提交并推送 YAML source truth 后，执行 `sub2api apply --target <target> --confirm`，按返回的 `job status` 命令轮询完成。
+6. 执行 `sub2api status --target <target>`，确认运行镜像等于 YAML 声明；滚动过程中短暂 `0/1` 先等待并复查，不要立即改账号池、Caddy 或 Secret。
+7. 执行 `sub2api validate --target <target>`、目标 public `/health` 和最小 public `/v1/responses` smoke；若需要确认未影响其它公开入口，再跑对应 target 的 `validate`。
 
 不要把镜像版本写进脚本常量、JSON 或 manifest 模板。
diff --git a/.agents/skills/unidesk-sub2api/references/troubleshooting-runtime.md b/.agents/skills/unidesk-sub2api/references/troubleshooting-runtime.md
index bc5889f7..59ba8218 100644
--- a/.agents/skills/unidesk-sub2api/references/troubleshooting-runtime.md
+++ b/.agents/skills/unidesk-sub2api/references/troubleshooting-runtime.md
@@ -1,6 +1,7 @@
 ## 运行面排障
 
 - `api.pikapython.com` 返回 502/503 时，先按 YAML 判定 target 和 failure layer。PK01 host-Docker target 先跑 `sub2api status --target PK01` 和 `sub2api validate --target PK01`，再分别检查 PK01 Caddy managed block、loopback app health、Docker container health、admin account availability 和最小 public `/v1/responses` smoke。k3s/FRP target 先跑对应 `sub2api status --target <id>` 和 `validate --target <id>`；若 `sub2api`、`sub2api-frpc`、`sub2api-redis` 或 `sub2api-egress-proxy` 出现 `0/1`，或 validate 显示 `no endpoints available for service "sub2api"` / app Pod 已终止，先用 `bun scripts/cli.ts platform-infra sub2api apply --target <id> --confirm` 重新收敛 YAML 资源，按返回的 `job status` 轮询，再跑 `status`、`validate` 和可用的 Codex-pool 验证。不要先改账号池、哨兵状态、Secret 或 Caddy。
+- 镜像升级或 `apply --confirm` 后，k3s target 可能短暂显示 `sub2api 0/1` 而 egress/frpc/redis 已 ready。先等待一轮并重跑 `status --target <id>`；若 `status --full` 显示目标 Pod Running/Ready、runtime image 等于 YAML、init containers Completed，则按滚动中间态处理并继续 `validate`。只有持续不 ready、事件显示拉取/启动失败、或 service proxy health 失败时，才进入运行面排障。
 - 快速恢复完成后，用分层证据 closeout：目标 public `/health` 应返回 200；最小公网 `/v1/responses` marker 应使用统一 key 或明确用户 key 返回 200；只输出 HTTP status、模型数量、marker、account id/group id 和 key fingerprint，不打印 key。不要为了公网验证运行 `configure-local --confirm`，它会重写本机 `~/.codex`；本机默认 `auth.json` key 返回 401 只能说明本机配置和公网统一 key 不一致，不能当作服务不可用证据。
 - Sub2API 卡在 `wait-postgres` / `wait-redis` 或服务内大量 `context deadline exceeded`：先跑 `sub2api status` 看 `networkPolicy.ok`，再跑 `sub2api validate` 看 `postgresCrossPodPgIsReady` / `redisCrossPodPing`；缺失或异常时用 `sub2api apply --confirm` 恢复受控 `NetworkPolicy/allow-all`，不要保留手工 iptables bypass 作为长期修复。
 - `codex-pool sync --confirm` 或 `codex-pool validate` 超时：先区分 CLI 传输超时和 Sub2API 运行失败。受控 CLI 应返回远端作业进度和 stdout/stderr tail；如果只是低层 `trans` 60s 超时，不能据此判定 Sub2API failover 不工作。改用或修复 CLI 的远端 job/poll 路径后重跑，并以最终结构化结果作为证据。
diff --git a/.agents/skills/unidesk-sub2api/references/validation.md b/.agents/skills/unidesk-sub2api/references/validation.md
index 65357b15..0efe2f2a 100644
--- a/.agents/skills/unidesk-sub2api/references/validation.md
+++ b/.agents/skills/unidesk-sub2api/references/validation.md
@@ -10,3 +10,5 @@
 - 若目标声明了 `egressProxy.enabled=true`，确认 proxy Deployment/Service ready，Sub2API 和 sentinel env 与 YAML 对齐，并通过 YAML 声明的 health URL 完成代理出站探针。
 
 如果要证明真实模型请求可用，使用最小 `/v1/responses` 或等价 Codex smoke。不要把 group-level `/v1/models` 成功解释成每个上游 account 都健康。
+
+公网 `/v1/responses` smoke 应尽量复用 `codex-pool validate` 的非流式请求形态：带统一 key、`stream:false`、`store:false`、小 `max_output_tokens`、短输入、`X-Request-ID` 和 `OpenAI-Client-Request-ID`，并用同一 request id 跑 `codex-pool trace --target <id> --request-id <id>` 取证。不要用没有超时的临时脚本或省略 request id 的公网 POST 作为最终证据；`/v1/models` 200 只能证明 key 和模型列表入口可用，不能替代 Responses smoke。