diff --git a/.github/actions/install-apt-deps/action.yml b/.github/actions/install-apt-deps/action.yml
index 5f692100c4..1e6222149f 100644
--- a/.github/actions/install-apt-deps/action.yml
+++ b/.github/actions/install-apt-deps/action.yml
@@ -24,11 +24,13 @@ inputs:
     description: >
       Tag of a prebuilt .deb bundle published to
       ghcr.io/<owner>/wolfssl-ci-debs by the ci-deps-image workflow
-      (e.g. "ubuntu-24.04-minimal"). When set, the packages are installed offline
-      from that bundle - the apt mirror is never contacted - and the apt
-      cache path below is skipped entirely. Any failure (bundle missing,
-      not public, or missing a package) falls through to the apt path, so
-      this is always safe to set. Leave empty to use apt only.
+      (e.g. "ubuntu-24.04-minimal"). When set, the packages are installed
+      offline from that bundle and the apt cache path below is skipped; on
+      that happy path the apt mirror is not contacted. The offline install
+      is all-or-nothing (a single --no-download install of the whole set),
+      so any failure - bundle missing, not public, or not covering every
+      requested package - falls back to the apt path. Always safe to set;
+      leave empty to use apt only.
     required: false
     default: ''
 runs:
diff --git a/.github/workflows/ci-deps-image.yml b/.github/workflows/ci-deps-image.yml
index ff8ac38a56..91cc5e6371 100644
--- a/.github/workflows/ci-deps-image.yml
+++ b/.github/workflows/ci-deps-image.yml
@@ -3,8 +3,11 @@ name: CI deps image
 # Builds the prebuilt apt .deb bundles that the make-check family (the
 # -minimal tags) and the interop workflows (the -full tags, a superset)
 # install offline (see .github/actions/install-apt-deps, input
-# ghcr-debs-tag). Each bundle is the .deb closure of a package list in
-# .github/ci-deps/, published to ghcr.io/<owner>/wolfssl-ci-debs:<tag>.
+# ghcr-debs-tag). Each bundle holds the .debs for a package list in
+# .github/ci-deps/ - every package plus the dependencies not already on the
+# matching runner image, so it is tied to that runner rather than being a
+# portable, self-contained closure - published to
+# ghcr.io/<owner>/wolfssl-ci-debs:<tag>.
 #
 # Why: the apt mirror times out often enough to break PR CI. Resolving the
 # closure ONCE here (on master, where a slow mirror only delays this job and
@@ -21,8 +24,10 @@ on:
   schedule:
     # Weekend only - refresh the bundles weekly so they track base-image
     # security updates. A mid-week package-list change waits for Saturday
-    # (or run this manually via workflow_dispatch); until then install-apt-deps
-    # falls back to apt for any package not yet in the bundle.
+    # (or run this manually via workflow_dispatch); until then the offline
+    # install (a single --no-download install of the whole set) fails if any
+    # requested package is missing from the bundle, and install-apt-deps
+    # falls back to the full apt path.
     - cron: '0 2 * * 6'
   workflow_dispatch: