From d2f7d3f407b2b3d5944e7ceea90a75c6f87cf93d Mon Sep 17 00:00:00 2001
From: "Kai (Tam Nhu) Tran" <61256810+kaitranntt@users.noreply.github.com>
Date: Sun, 17 May 2026 06:13:55 -0400
Subject: [PATCH] docs(ci): clarify rc.1 soak and :full removal as intentional
 design (#1261) (#1279)

Reviewer kept flagging :full omission and stale :latest as bugs. Both are intentional per Q3 maintainer decision and the rc.1 soak design (loop-5). Strengthen inline comments to make this unmistakable to future readers.
---
 .github/workflows/docker-release.yml | 17 +++++++++++++----
 docker/Dockerfile.integrated         | 10 +++++++---
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/docker-release.yml b/.github/workflows/docker-release.yml
index e137be67..84b6829b 100644
--- a/.github/workflows/docker-release.yml
+++ b/.github/workflows/docker-release.yml
@@ -400,10 +400,19 @@ jobs:
   # ---------------------------------------------------------------------------
   # Job 4: Promote mutable tags — runs ONLY after smoke tests pass
   # Adds :latest, :<major>, :<minor> aliases pointing to the immutable digest.
-  # Never triggered automatically by release events — requires an explicit
-  # workflow_dispatch with promote_to_latest=true (via promote-release.yml or
-  # direct gh CLI call) after the operator confirms the immutable :<ver> image
-  # is stable. This is the sole rc.1 soak gate for Docker mutable tags.
+  #
+  # INTENTIONAL DESIGN (issue #1251 rc.1 soak — see docs/release-process.md):
+  # GitHub release events publish ONLY the immutable :<ver> tag. The mutable
+  # :latest / :<major> / :<minor> aliases STAY POINTED AT THE PRIOR STABLE
+  # RELEASE until an operator manually promotes after a soak window (~24h).
+  # Trade-off: zero-install users (curl ccs.kaitran.ca/docker-compose.yaml &&
+  # docker compose up -d) keep receiving last-known-good :latest during the
+  # soak; operators wanting the new version pull :<ver> directly.
+  #
+  # Operator promotion:
+  #   gh workflow run promote-release.yml -f tag=v<X.Y.Z>
+  # (or equivalently: gh workflow run "Publish Docker Image" -f tag=v<X.Y.Z>
+  # -f promote_to_latest=true)
   # ---------------------------------------------------------------------------
   promote-mutable-tags:
     name: Promote mutable tags (:latest / major / minor)
diff --git a/docker/Dockerfile.integrated b/docker/Dockerfile.integrated
index f40be85b..c4a6e3ab 100644
--- a/docker/Dockerfile.integrated
+++ b/docker/Dockerfile.integrated
@@ -3,9 +3,13 @@ FROM eceasy/cli-proxy-api:latest
 ARG CCS_NPM_VERSION=latest
 
 # CCS integrated image: CCS CLI + CLIProxy + supervisord.
-# No AI CLIs (claude-code, gemini-cli, etc.) are bundled.
-# To use AI CLIs alongside CLIProxy, run them in sibling containers
-# attached to ccs-net — see docker/README.md#connect-your-app-to-cliproxy.
+# Design choice (issue #1251 final scope): single-image strategy. The originally-
+# proposed `:full` variant bundling claude-code/gemini-cli/grok-cli/opencode was
+# DROPPED on maintainer review. Rationale: smaller surface area, fewer supply-
+# chain dependencies, simpler tag taxonomy. Users needing AI CLIs run them in
+# sibling containers attached to ccs-net — the public DNS contract guarantees
+# http://ccs:8317 reachability. See docker/README.md#connect-your-app-to-
+# cliproxy. Historical record: CHANGELOG.md "### Removed" entry.
 
 RUN apk add --no-cache \
     curl \