diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bf07d81
--- /dev/null
+++ b/README.md
@@ -0,0 +1,375 @@
+# GHBot - Discord Sound Effects Bot
+
+A modern Discord bot built with Discord.js v14 that provides sound effects, text commands, fun facts, and scheduled events for Discord servers.
+
+## ✨ Features
+
+### 🔊 Sound Effects
+
+- **Prefix commands**: `!sfx <sound>` - Classic text-based commands
+- **Slash commands**: `/sfx` with autocomplete - Modern Discord UI with searchable sound effects
+- Automatic sound discovery from the `sfx/` directory
+- Configurable volume and channel restrictions per guild
+
+### 💬 Text Commands
+
+- **Fun Facts**: Random or specific fact retrieval (`!funfact [number]`)
+- **Ham Facts**: Ham radio related facts (`!hamfact [number]`)
+- **Static Commands**: Custom text responses loaded from configuration files
+- **Ankhbot Import**: Support for imported Ankhbot command databases
+
+### 🎭 Interactive Features
+
+- **Role Management**: Self-service role assignment (`!role add/remove <role>`)
+- **Dance Command**: ASCII art dance animation
+- **Voice Controls**: Join/leave voice channels (`!join`, `!leave`)
+
+### ⏰ Scheduling
+
+- **Scheduled Events**: Cron-based message scheduling with role pings
+- **Activity Rotation**: Automatic bot status updates
+
+### 🛠️ Admin Features
+
+- **Multi-guild Support**: Configure different settings per Discord server
+- **Hot Reload**: Configuration files update without restart
+- **Admin Commands**: Bot management and restart capabilities
+- **Blacklist System**: Block specific users from using commands
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js 22 LTS
+- pnpm package manager
+- Discord Bot Token (see Discord Setup section below)
+
+### Installation
+
+1. **Clone the repository**
+
+   ```bash
+   git clone https://github.com/greenham/ghbot.git
+   cd ghbot
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   pnpm install
+   ```
+
+3. **Configure the bot**
+
+   ```bash
+   cp config.example.json config.json
+   # Edit config.json with your bot token and guild settings
+   ```
+
+4. **Set up Discord Bot** (see Discord Setup section below)
+
+5. **Run the bot**
+
+   ```bash
+   # Development mode with auto-reload
+   pnpm dev
+
+   # Production mode
+   pnpm start
+   ```
+
+## 🐳 Docker Deployment
+
+### Build and Run
+
+```bash
+# Build the Docker image
+pnpm docker:build
+
+# Run the container
+pnpm docker:run
+```
+
+### Using Docker Compose
+
+```yaml
+version: "3.8"
+services:
+  ghbot:
+    build: .
+    restart: unless-stopped
+    volumes:
+      - ./config.json:/app/config.json:ro
+      - ./sfx:/app/sfx:ro
+      - ./conf:/app/conf:ro
+```
+
+## 📖 Usage
+
+### Sound Effects
+
+**Prefix Command:**
+
+```
+!sfx albert          # Play 'albert' sound effect
+!sfx                 # List all available sounds
+```
+
+**Slash Command:**
+
+```
+/sfx sound: albert   # Play with autocomplete suggestions
+```
+
+### Text Commands
+
+```
+!funfact             # Random fun fact
+!funfact 42          # Specific fun fact #42
+!hamfact             # Random ham radio fact
+!dance               # ASCII dance animation
+```
+
+### Role Management
+
+```
+!role add streamer   # Add the 'streamer' role
+!role remove vip     # Remove the 'vip' role
+```
+
+### Voice Commands
+
+```
+!join                # Join your voice channel
+!leave               # Leave current voice channel
+```
+
+## 🔧 Discord Setup
+
+### Creating a Discord Bot
+
+1. **Go to Discord Developer Portal**
+   - Visit https://discord.com/developers/applications
+   - Click "New Application" and give it a name
+
+2. **Create Bot User**
+   - Go to the "Bot" section
+   - Click "Add Bot"
+   - Copy the bot token for your config.json
+
+3. **Enable Required Intents**
+   Under "Privileged Gateway Intents", enable:
+   - **SERVER MEMBERS INTENT** (Required for role management)
+   - **MESSAGE CONTENT INTENT** (Required for prefix commands)
+
+4. **Bot Permissions**
+   When inviting the bot, ensure it has these permissions:
+   - Send Messages
+   - Embed Links
+   - Read Message History
+   - Connect (for voice channels)
+   - Speak (for voice channels)
+   - Use Voice Activity
+   - Manage Roles (if using role commands)
+
+5. **Invite Bot to Server**
+   - Go to "OAuth2 > URL Generator"
+   - Select "bot" and "applications.commands" scopes
+   - Select the permissions listed above
+   - Use the generated URL to invite your bot
+
+## ⚙️ Configuration
+
+### Basic Configuration
+
+Copy `config.example.json` to `config.json` and customize:
+
+```json
+{
+  "botName": "YourBot",
+  "debug": false,
+  "discord": {
+    "token": "YOUR_BOT_TOKEN",
+    "adminUserId": "YOUR_DISCORD_USER_ID",
+    "guilds": [
+      {
+        "id": "GUILD_ID",
+        "internalName": "My Server",
+        "prefix": "!",
+        "enableSfx": true,
+        "allowedSfxChannels": "general|voice-chat",
+        "sfxVolume": 0.5,
+        "enableFunFacts": true,
+        "enableHamFacts": true
+      }
+    ],
+    "activities": ["Playing sounds", "Serving facts"],
+    "blacklistedUsers": []
+  }
+}
+```
+
+### Sound Effects Setup
+
+1. Add `.mp3` or `.wav` files to the `sfx/` directory
+2. Files are automatically discovered (filename becomes command name)
+3. Sounds appear in slash command autocomplete
+
+### Static Commands
+
+Edit `conf/text_commands` with pipe-separated commands:
+
+```
+hello|Hello there!
+wiki,wikipedia|https://wikipedia.org
+help,commands|Available commands: !sfx, !funfact, !hamfact
+```
+
+### Scheduled Events
+
+Add to guild configuration:
+
+```json
+"scheduledEvents": [
+  {
+    "id": "daily-greeting",
+    "schedule": "0 9 * * *",
+    "channelId": "CHANNEL_ID",
+    "message": "Good morning everyone!",
+    "pingRoleId": "ROLE_ID"
+  }
+]
+```
+
+## 🏗️ Architecture
+
+```
+src/
+├── index.js                 # Main bot entry point
+├── config/
+│   ├── config.js            # Configuration loader
+│   └── intents.js          # Discord gateway intents
+├── commands/
+│   ├── prefix/             # Traditional prefix commands
+│   └── slash/              # Modern slash commands
+├── services/
+│   ├── voiceService.js     # Voice connection management
+│   ├── commandLoader.js    # Static/Ankhbot command loader
+│   ├── sfxManager.js       # Sound effect file management
+│   └── schedulerService.js # Scheduled events handler
+└── utils/
+    └── helpers.js          # Utility functions
+```
+
+## 🧪 Development
+
+### Running in Development Mode
+
+```bash
+pnpm dev  # Uses nodemon for auto-reload
+```
+
+### Adding New Commands
+
+**Prefix Command Example:**
+
+```javascript
+// src/commands/prefix/hello.js
+module.exports = {
+  name: "hello",
+  description: "Say hello",
+
+  async execute(message, args, guildConfig) {
+    await message.channel.send("Hello there!");
+  },
+};
+```
+
+**Slash Command Example:**
+
+```javascript
+// src/commands/slash/ping.js
+const { SlashCommandBuilder } = require("discord.js");
+
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName("ping")
+    .setDescription("Replies with Pong!"),
+
+  async execute(interaction, guildConfig) {
+    await interaction.reply("Pong!");
+  },
+};
+```
+
+## 📊 System Requirements
+
+- **Node.js**: 22 LTS or higher
+- **Memory**: 256MB+ RAM
+- **Storage**: 500MB+ (depending on sound effects)
+- **Network**: Stable internet connection for Discord API
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**"Used disallowed intents" Error**
+
+- Enable required intents in Discord Developer Portal (see Discord Setup section above)
+- Ensure SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT are enabled
+
+**Voice/Audio Issues**
+
+- Ensure ffmpeg is installed (handled automatically in Docker)
+- Check bot has Connect and Speak permissions
+- Verify voice channel isn't full or restricted
+
+**Slash Commands Not Appearing**
+
+- Commands register on bot startup
+- May take up to 1 hour to appear globally
+- Try restarting the bot
+
+**Permission Errors**
+
+- Ensure bot has necessary permissions in channels
+- Check role hierarchy (bot role should be above managed roles)
+
+### Debug Mode
+
+Enable debug logging in `config.json`:
+
+```json
+{
+  "debug": true
+}
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit changes: `git commit -m 'Add amazing feature'`
+4. Push to branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [Discord.js v14](https://discord.js.org/)
+- Audio processing via [@discordjs/voice](https://github.com/discordjs/voice)
+- Inspired by the original AnkhBot command system
+- Special thanks to the Discord.js community
+
+## 📞 Support
+
+- Create an [Issue](https://github.com/greenham/ghbot/issues) for bug reports
+- Check the Discord Setup section above for configuration help
+- Review [CLAUDE.md](CLAUDE.md) for development guidance
+
+---
+
+Made with ❤️ for Discord communities