diff --git a/.env.example b/.env.example
index 1f332f8..d745ee3 100644
--- a/.env.example
+++ b/.env.example
@@ -87,6 +87,35 @@ SSH_KEY_PATH=~/.ssh
 # MEMPALACE_PI_REMOTE_PATH=/data/feed
 # MEMPALACE_PI_DEVICE=
 
+# ── Mailbox notification: MUST BE NAMED, auto-detect CANNOT work here ──
+# The mempalace extension polls the logstream for fleet asks addressed to this
+# device and queues them into the next turn. That part needs no config. The
+# NOTIFICATION that tells the human it happened does, and unset means SILENT
+# outside the pi TUI.
+#
+# Why there is no working default: terminal identity lives in env vars set by
+# the emulator (KITTY_WINDOW_ID, TERM_PROGRAM) and `docker exec` does NOT
+# forward them — inside the container pi sees only TERM=xterm-256color no matter
+# what is rendering it. So "desktop" auto-detection always falls through to
+# OSC 777, which Kitty does not implement, and the notification silently does
+# nothing: the worst outcome for a feature whose only job is to break a silence.
+# Naming the protocol is what makes it fire.
+#
+#   kitty    OSC 99 desktop notification (correct for Kitty, incl. over SSH)
+#   osc777   OSC 777 (tmux/iTerm2/foot and others)
+#   desktop  OSC 99 if KITTY_WINDOW_ID is visible, else OSC 777 — inside a
+#            container that means effectively always OSC 777, so prefer naming
+#   0 / off  suppress entirely (in-TUI notify still shows)
+# MEMPALACE_MAILBOX_NOTIFY=kitty
+#
+# Cadence, if the delivery ever feels late: the poll is coupled to session
+# activity (it runs when the agent settles), NOT to a wall clock.
+# MEMPALACE_MAILBOX_POLL_MS is therefore a FLOOR BETWEEN POLLS (default 300000),
+# not a promise of one every 5 minutes — an idle session polls zero times, and
+# session start does the first look.
+# MEMPALACE_MAILBOX_POLL_MS=300000
+# MEMPALACE_MAILBOX_RESURFACE_MS=3600000
+
 # ── LAN access from the container (host-OS-agnostic) ─────────────────
 # On VM-backed hosts (macOS OrbStack / Docker Desktop) the container can't
 # reach the host's directly-attached LAN peers by default. The entrypoint