diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0a15991
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# SHSF Discord Bot
+
+A modular TypeScript Discord bot for SHSF, designed for clarity, extensibility, and easy maintenance.
+
+## Features
+- **Command Handling:** Add commands in `src/commands/` and register them via `src/handlers/registerCommands.ts`.
+- **Event Listeners:** Handle Discord events in `src/listeners/`, grouped by event type.
+- **Startup Routines:** Add startup logic in `src/handlers/startup/` and load via `src/lib/loadStartupHandlers.ts`.
+- **Web Endpoints:** Serve bot-related endpoints from `src/web/` using `src/webserver.ts`.
+- **Centralized Configuration:** Manage settings in `src/config.ts`.
+
+## Project Structure
+```
+src/
+  commands/           # Bot commands (e.g., ping.ts)
+  handlers/           # Command registration & startup routines
+    startup/          # Startup logic (e.g., rotatingActivity.ts)
+  listeners/          # Discord event handlers (e.g., messageCreate/logMessage.ts)
+  lib/                # Shared utilities (e.g., commandRegistry.ts)
+  web/                # Web endpoints (e.g., gitCommit.ts)
+  config.ts           # Bot configuration
+  types.ts            # Type definitions
+  webserver.ts        # Web server entry point
+  index.ts            # Bot entry point
+```
+
+## Getting Started
+1. **Install dependencies:**
+   ```bash
+   pnpm install
+   ```
+2. **Configure the bot:**
+   Edit `src/config.ts` with your Discord bot token and settings.
+3. **Run the bot:**
+   ```bash
+   pnpm start
+   # or
+   node src/index.ts
+   ```
+
+## Adding Features
+- **New Command:** Create a file in `src/commands/`, register in `src/handlers/registerCommands.ts`.
+- **New Event Handler:** Add a handler in the relevant `src/listeners/<Event>/` folder.
+- **Startup Routine:** Implement in `src/handlers/startup/`, register via `src/lib/loadStartupHandlers.ts`.
+- **Web Endpoint:** Add to `src/web/`, served by `src/webserver.ts`.
+
+## Development Notes
+- Uses [pnpm](https://pnpm.io/) for dependency management.
+- No tests or linting scripts by default; add as needed in `package.json`.
+- Modular structure allows easy debugging and targeted development.
+
+## References
+- [src/index.ts](src/index.ts): Bot entry point
+- [src/webserver.ts](src/webserver.ts): Web server entry point
+- [src/handlers/registerCommands.ts](src/handlers/registerCommands.ts): Command registration
+- [src/lib/commandRegistry.ts](src/lib/commandRegistry.ts): Command registry utility
+- [src/listeners/messageCreate/logMessage.ts](src/listeners/messageCreate/logMessage.ts): Example event handler
+
+---
+
+For questions or improvements, see `.github/copilot-instructions.md`.