From 5d62c7a15144714572189f739ce71223167e8046 Mon Sep 17 00:00:00 2001
From: Masami <masami-agent@users.noreply.github.com>
Date: Tue, 14 Apr 2026 12:22:13 +0000
Subject: [PATCH] fix: improve gateway intents and auth error messages

Catch DisallowedGatewayIntents and InvalidAuthentication errors from
Discord gateway with actionable error messages instead of cryptic
serenity errors.

Add prerequisites section to README documenting required Discord
Developer Portal settings.

Closes #116
---
 README.md   | 15 ++++++++++++++-
 src/main.rs | 23 +++++++++++++++++++++--
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 6ad1dbcd..025cba52 100644
--- a/README.md
+++ b/README.md
@@ -29,10 +29,23 @@ A lightweight, secure, cloud-native ACP harness that bridges Discord and any [Ag
 
 ## Quick Start
 
-### 1. Create a Discord Bot
+### 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-bot-howto.md](docs/discord-bot-howto.md) for a detailed step-by-step guide.
 
+### 1. Create a Discord Bot
+
+Follow the [prerequisites](#prerequisites) above, then create your bot.
+
 ### 2. Install with Helm (Kiro CLI — default)
 
 ```bash
diff --git a/src/main.rs b/src/main.rs
index fd63b89a..3898d160 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -6,11 +6,12 @@ mod format;
 mod reactions;
 mod stt;
 
+use serenity::gateway::GatewayError;
 use serenity::prelude::*;
 use std::collections::HashSet;
 use std::path::PathBuf;
 use std::sync::Arc;
-use tracing::info;
+use tracing::{error, info};
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
@@ -98,7 +99,25 @@ async fn main() -> anyhow::Result<()> {
     });
 
     info!("starting discord bot");
-    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(_) => {}
+    }
 
     // Cleanup
     cleanup_handle.abort();