diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4714b1..c4235de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,19 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
 
 ## Unreleased
 
+### Changed
+
+- **Secrets are now delivered to the container via `env_file: .env` only; the
+  `environment:` block no longer re-declares `GITEA_ACCESS_TOKEN`,
+  `GITEA_HOST`, or `GITHUB_PERSONAL_ACCESS_TOKEN`.** An `environment:` entry
+  both overrides `env_file:` and is interpolated from the host shell, so a
+  stale shell export (e.g. one auto-loaded by an opencode/dotenv hook) would
+  silently shadow the value in your `.env` — an updated token in `.env` never
+  reached the container. Delivering secrets via `env_file` only decouples the
+  container from whatever the host shell happens to export. No action needed:
+  `.env.example` already documents every supported variable. Affects
+  `docker-compose.yml` and the README “basic shape” snippet.
+
 ### Fixed (CI)
 
 - **`promote-base-latest` now re-points `base-latest` reliably after a
diff --git a/README.md b/README.md
index f07f249..61307c7 100644
--- a/README.md
+++ b/README.md
@@ -319,9 +319,10 @@ services:
     environment:
       - TERM=xterm-256color
       # - STUDIO_EXPOSE=1          # -studio only: auto-start the socat bridge on boot
-      - GITEA_ACCESS_TOKEN=${GITEA_ACCESS_TOKEN:-}
-      - GITEA_HOST=${GITEA_HOST:-}
-      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN:-}
+      # Secrets (GITEA_*, GITHUB_*, …) come from env_file: .env above — not
+      # duplicated here. An environment: entry overrides env_file and is
+      # interpolated from the host shell, so a stale shell export would
+      # silently shadow your .env. See .env.example for the full list.
     volumes:
       # Workspace: your host source tree
       - ${WORKSPACE_PATH:-.}:/workspace
diff --git a/docker-compose.yml b/docker-compose.yml
index 3cf9930..657a3f0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -31,9 +31,13 @@ services:
       - .env
     environment:
       - TERM=xterm-256color
-      - GITEA_ACCESS_TOKEN=${GITEA_ACCESS_TOKEN:-}
-      - GITEA_HOST=${GITEA_HOST:-}
-      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN:-}
+      # Secrets (GITEA_*, GITHUB_*, and any others) are delivered to the
+      # container via `env_file: .env` above — do NOT duplicate them here.
+      # An `environment:` entry overrides env_file AND is interpolated from
+      # the host shell, so a stale shell export (e.g. one auto-loaded by a
+      # dotenv hook) would silently shadow the value in your .env. Keeping
+      # secrets env_file-only decouples the container from the host shell.
+      # See .env.example for the full list of supported variables.
     volumes:
       # Host workspace — mount your project here
       - ${WORKSPACE_PATH:-.}:/workspace