diff --git a/docker-compose.yml b/docker-compose.yml
index 91bc8c6..3d66366 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,9 +7,11 @@
 # Just bring it up — everything (incl. Ollama models) comes up automatically:
 #   docker compose up -d --build
 #
-# The Discord token can be added LAST: without it the desktop, brain bridge,
-# Ollama and models all run; only the bot waits. Then put DISCORD_BOT_TOKEN in
-# .env and re-run `docker compose up -d`.
+# The Discord credential can be added LAST: without it the desktop, brain
+# bridge, Ollama and models all run; only the bot waits. This deployment runs
+# in userbot mode, so put DISCORD_SELFBOT_TOKEN in .env and re-run
+# `docker compose up -d`. (A normal-bot DISCORD_BOT_TOKEN is optional and only
+# needed for the legacy slash-command bot; leave it blank for userbot mode.)
 #
 # Watch the desktop:  VNC viewer -> localhost:5901  (or browser -> localhost:6080)
 # ============================================================================
diff --git a/docker/run-bot.sh b/docker/run-bot.sh
index 06ec238..d0c8dec 100755
--- a/docker/run-bot.sh
+++ b/docker/run-bot.sh
@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
 # Wait for the brain bridge, then run the Discord bot.
 #
-# The Discord token is intentionally deferred: if DISCORD_BOT_TOKEN is not set
+# The Discord credential is intentionally deferred: if no usable token is set
 # yet, the rest of the stack (desktop, bridge, ollama) still runs fully. The bot
-# just waits. Add the token to .env and `docker compose up -d` to start it.
+# just waits. Add a token to .env (DISCORD_SELFBOT_TOKEN for userbot mode, or
+# DISCORD_BOT_TOKEN + DISCORD_APP_ID for the legacy normal bot) and
+# `docker compose up -d` to start it.
 set -e
 cd /app/bot