1 files changed, 64 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7a8d638
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# Timeoutinator
+
+A Discord bot that instantly **timeouts** anyone who posts in a configured channel and **purges** all of their messages from the last 24 hours.
+
+## How it works
+
+1. User sends a message in the policed channel.
+2. Bot immediately times them out (`Moderate Members` — configurable duration, default 1 hour).
+3. Bot bulk-deletes every message that user posted **in any channel of the guild** over the past 24 hours (including the triggering message).
+
+Bots, system messages, and webhook messages are ignored. The bot's own messages are also ignored. Concurrent handling of the same user is deduplicated so rapid-fire spam doesn't cause duplicate timeouts or purge races.
+
+## Setup
+
+### 1. Create a Discord Application
+
+1. Go to [discord.com/developers/applications](https://discord.com/developers/applications)
+2. Click **New Application** → name it → **Bot** tab → **Add Bot**
+3. Under the bot, click **Reset Token** and copy the token — this is your `DISCORD_TOKEN`
+
+### 2. Enable Required Intents
+
+In the **Bot** tab, scroll to **Privileged Gateway Intents**.  
+The bot only needs **Message Content** if you want to read message content — by default, only `GUILD_MESSAGES` is required, which is non-privileged. No privileged intents are required.
+
+### 3. Invite the Bot
+
+Use this URL (replace `YOUR_BOT_CLIENT_ID` with the bot's Client ID from the **General Information** tab):
+
+```
+https://discord.com/api/oauth2/authorize?client_id=YOUR_BOT_CLIENT_ID&permissions=1099511702528&scope=bot
+```
+
+Required permissions (encoded in the URL):
+
+| Permission              | Why                                      |
+|-------------------------|------------------------------------------|
+| View Channels           | See the policed channel and the channels to purge                  |
+| Read Message History    | Fetch messages to purge                  |
+| Manage Messages         | Delete messages via bulk-delete endpoint |
+| Moderate Members        | Apply timeouts                           |
+
+### 4. Run
+
+```bash
+cp .env.example .env   # or export the env vars directly
+# edit .env with your token and target channel ID
+
+cargo run --release
+```
+
+## Environment Variables
+
+| Variable              | Required | Default | Description                                                    |
+|-----------------------|----------|---------|----------------------------------------------------------------|
+| `DISCORD_TOKEN`       | ✅       | —       | Bot token from the Discord Developer Portal                    |
+| `TARGET_CHANNEL_ID`   | ✅       | —       | Snowflake ID of the channel to police (right-click → Copy ID) |
+| `TIMEOUT_MINUTES`     | ❌       | `60`    | Timeout duration in minutes (1–40320, i.e. up to 28 days)     |
+| `PURGE_HOURS`         | ❌       | `24`    | How far back (hours) to look when deleting messages           |
+
+## Requirements
+
+- Rust 1.85+ (edition 2024)
+- Network access (to fetch crates and connect to Discord's gateway)