diff --git a/env.sample.oauth-multi-user b/env.sample.oauth-multi-user
index 15a40f13..3ef9962e 100644
--- a/env.sample.oauth-multi-user
+++ b/env.sample.oauth-multi-user
@@ -33,6 +33,13 @@ NEXTCLOUD_OIDC_CLIENT_SECRET=<your-client-secret>
 # MCP Server URL (for OAuth redirects)
 NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
 
+# ===== REQUIRED: APP-PASSWORD STORAGE =====
+# Required for login_flow — per-user Nextcloud app passwords are stored here
+# (encrypted) so they survive restarts. See docs/login-flow-v2.md#setup.
+# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+TOKEN_ENCRYPTION_KEY=<your-encryption-key>
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
 # ===== OPTIONAL: SEMANTIC SEARCH (Recommended) =====
 # AI-powered semantic search with automatic background operation setup
 #
@@ -58,11 +65,6 @@ OLLAMA_EMBEDDING_MODEL=nomic-embed-text
 #AWS_REGION=us-east-1
 #BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
 
-# Token Storage (required for background operations - auto-enabled by semantic search)
-# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-TOKEN_ENCRYPTION_KEY=<your-encryption-key>
-TOKEN_STORAGE_DB=/app/data/tokens.db
-
 # ===== OPTIONAL: DOCUMENT PROCESSING =====
 # Extract text from PDFs, images, DOCX for semantic search
 #ENABLE_DOCUMENT_PROCESSING=true