diff --git a/.env.example b/.env.example
index bee2d69..b03361f 100644
--- a/.env.example
+++ b/.env.example
@@ -52,6 +52,13 @@ SSH_KEY_PATH=~/.ssh
 # DEVBOX_ATELIER=1
 
 # ── Git Configuration ────────────────────────────────────────────────
+# Set BOTH. If unset, every repo inside the container fails with
+# "Author identity unknown" on first commit, and an agent asked to commit
+# will guess an identity from git log — often the wrong one. The e-mail is
+# per-machine (work machines use the corporate address, personal machines the
+# private one), so it belongs in this per-machine .env, never in a skill or a
+# repo-local override. Consumed by entrypoint-user.sh -> ~/.gitconfig, which is
+# NOT persistent across container recreate — this file is the source of truth.
 GIT_USER_NAME=
 GIT_USER_EMAIL=