diff --git a/.doc/ops/short-term/2026-09-27-docker-context-gitkeep.md b/.doc/ops/short-term/2026-09-27-docker-context-gitkeep.md
new file mode 100644
index 00000000..d4da50bf
--- /dev/null
+++ b/.doc/ops/short-term/2026-09-27-docker-context-gitkeep.md
@@ -0,0 +1,47 @@
+---
+title: "修复 docker 构建上下文缺少 web/dist/.gitkeep 导致候选镜像构建失败"
+task_id: docker-context-gitkeep-2026-09-27
+status: in_progress
+created: 2026-09-27
+updated: 2026-09-27
+owner: pi
+task_type: fix
+task_tier: small
+policy_revision: "AGENTS+worktree-ops @ 94c215d3"
+branch: fix/docker-context-gitkeep-2026-09-27
+worktree: .worktrees/docker-context-gitkeep-2026-09-27
+base_dev_sha: "94c215d36e090ad6c1541f64bd625067d7fce4fc"
+write_scope:
+  - .dockerignore
+  - .doc/ops/short-term/2026-09-27-docker-context-gitkeep.md
+allowed_environments: ["dev"]
+capabilities: [git:dev, env:dev]
+mutex: env:dev
+review_state: pending
+integration_state: pending
+deployment: not_required
+cleanup: pending
+remote_sync: not_requested
+---
+
+# 修复 docker 构建上下文缺少 web/dist/.gitkeep
+
+## 问题与根因（已证实）
+
+- 症状：`candidate-images-build.sh --commit 94c215d3` 在 go-builder 阶段失败：`web/embed.go:14:12: pattern all:dist: no matching files found`。
+- 根因：`.dockerignore` 的 `web/dist` 行把整个目录排除出构建上下文；`web/embed.go`（`//go:embed all:dist`，6cbe7e6e 2026-09-24 16:20 落地）依赖 git 内的 `web/dist/.gitkeep` 使模式可满足。两者组合后上下文内无任何 `web/dist` 条目 → embed 失败。
+- 时间线：最后一次成功候选镜像构建 = `3de5bc5c`（2026-09-24 03:24，早于 embed.go）。即自单二进制 P1 合入起 docker 镜像构建已坏，因 dev 转非容器、test/main 未重建而未暴露。本次 dev→test 晋升（--require-digests 门禁）首次触发。
+- 影响：所有需要 image_digests 的晋升/发布门禁（dev→test、test→main）被阻断。
+
+## 修复
+
+`.dockerignore` 在 `web/dist` 排除后追加 `!web/dist/.gitkeep` 负向规则：上下文仅含 `.gitkeep`，embed 模式可满足；容器运行时行为不变（镜像内 dist 仍来自 web-builder 阶段 `COPY --from=web-builder /web/dist`，embed 内无 index.html → `LookupDist` false → 磁盘回退，与 P1 之前语义一致）。
+
+## 验证
+
+真实执行 `candidate-images-build.sh --commit <本修复提交>`：app/events/pi-agent 三镜像构建成功并产出 digests（即晋升同款路径）。
+
+## 关联
+
+- 触发任务：test-single-binary-2026-09-27（晋升 rc-v1.1.0-beta.4 需 digests 收据）。
+- 同期发现的独立缺陷（另立跟进，不在本修复内）：sysadmin 初始 apply 空 key 清空 runner models.json（internal/app/app.go + internal/sysadmin/apply.go）；launch.sh sidecar 子 shell 相对 DATA_DIR 扩展路径解析。
diff --git a/.dockerignore b/.dockerignore
index 50ab2b20..f03a7106 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -7,6 +7,7 @@ data
 .tmp
 web/node_modules
 web/dist
+!web/dist/.gitkeep
 web/.vite
 bin
 *.md