diff --git a/README.md b/README.md
index 71981c70..c705dc48 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,19 @@ A lightweight, secure, cloud-native ACP harness that bridges **Discord, Slack**,
 
 ## Quick Start
 
+### Prerequisites
+
+Before running openab, enable these in the [Discord Developer Portal](https://discord.com/developers/applications):
+
+1. **Bot → Privileged Gateway Intents**:
+   - ✅ Message Content Intent
+   - ✅ Server Members Intent
+2. **OAuth2 → URL Generator → Bot Permissions**:
+   - Send Messages, Embed Links, Attach Files
+   - Read Message History, Add Reactions
+
+See [docs/discord.md](docs/discord.md) for a detailed step-by-step guide.
+
 ### 1. Create a Bot
 
 <details>
diff --git a/src/main.rs b/src/main.rs
index 5e94dcdd..6d5c3135 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -16,6 +16,7 @@ mod gateway;
 
 use adapter::AdapterRouter;
 use clap::Parser;
+use serenity::gateway::GatewayError;
 use serenity::prelude::*;
 use std::collections::HashSet;
 use std::path::PathBuf;
@@ -336,7 +337,25 @@ async fn main() -> anyhow::Result<()> {
         });
 
         info!("discord bot running");
-        client.start().await?;
+        match client.start().await {
+            Err(serenity::Error::Gateway(GatewayError::DisallowedGatewayIntents)) => {
+                error!(
+                    "Discord rejected privileged intents. \
+                     Enable MESSAGE CONTENT INTENT at: \
+                     https://discord.com/developers/applications → Bot → Privileged Gateway Intents"
+                );
+                std::process::exit(1);
+            }
+            Err(serenity::Error::Gateway(GatewayError::InvalidAuthentication)) => {
+                error!(
+                    "Discord rejected bot token. \
+                     Verify your bot_token in config.toml is correct and has not been reset."
+                );
+                std::process::exit(1);
+            }
+            Err(e) => return Err(e.into()),
+            Ok(_) => {}
+        }
     } else {
         // No Discord — wait for SIGINT or SIGTERM
         info!("running without discord, press ctrl+c to stop");