Add Discord.js bot base with prefix commands and Winston logging

Co-authored-by: yhqe <139268606+yhqe@users.noreply.github.com>

README.md

@@ -1,2 +1,120 @@
-# twitter_v3
-discord moderation bort
+# twitter_v3 — Discord Moderation Bot
+
+A Discord.js **v14** bot base using traditional **prefix commands** (no slash commands) and structured **Winston logging**.
+
+---
+
+## Features
+
+- 📨 **Prefix command system** — commands triggered by a configurable prefix (default `!`)
+- 📁 **Auto-loading** — commands and events are loaded automatically from their folders
+- 🔖 **Aliases** — each command can define one or more aliases
+- 📝 **Winston logging** — coloured console output + rolling log files (`logs/combined.log`, `logs/error.log`)
+- 🛡️ **Global error handling** — unhandled rejections and uncaught exceptions are caught and logged
+
+---
+
+## Project Structure
+
+```
+src/
+├── index.js               # Entry point — creates the client, loads handlers
+├── commands/
+│   ├── help.js            # !help — lists commands or shows command detail
+│   └── ping.js            # !ping — latency check
+├── events/
+│   ├── ready.js           # Fires once when the bot is online
+│   └── messageCreate.js   # Parses every message for prefix commands
+├── handlers/
+│   ├── commandHandler.js  # Reads src/commands/ and registers commands
+│   └── eventHandler.js    # Reads src/events/ and registers Discord events
+└── utils/
+    └── logger.js          # Winston logger instance
+logs/                      # Created automatically at runtime (git-ignored)
+```
+
+---
+
+## Setup
+
+### 1. Clone & install dependencies
+
+```bash
+git clone https://github.com/yhqe/twitter_v3.git
+cd twitter_v3
+npm install
+```
+
+### 2. Configure environment variables
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in:
+
+| Variable    | Required | Description                                          |
+|-------------|----------|------------------------------------------------------|
+| `BOT_TOKEN` | ✅ Yes   | Your bot token from the Discord Developer Portal     |
+| `PREFIX`    | ❌ No    | Command prefix (default: `!`)                        |
+| `GUILD_ID`  | ❌ No    | Test server ID (handy for dev utilities)             |
+
+### 3. Enable the Message Content intent
+
+Go to your application in the [Discord Developer Portal](https://discord.com/developers/applications), open **Bot → Privileged Gateway Intents**, and enable **Message Content Intent**. This is required for prefix commands.
+
+### 4. Start the bot
+
+```bash
+# Production
+npm start
+
+# Development (auto-restarts on file changes, Node.js 18+)
+npm run dev
+```
+
+---
+
+## Adding Commands
+
+Create a file in `src/commands/`. The handler will load it automatically on next start.
+
+```js
+'use strict';
+
+module.exports = {
+  name: 'example',           // Primary command name (also used as the key)
+  description: 'An example command.',
+  aliases: ['ex'],           // Optional aliases
+  usage: 'example <text>',   // Shown in !help example
+
+  async execute(client, message, args) {
+    await message.reply(`You said: ${args.join(' ')}`);
+  },
+};
+```
+
+## Adding Events
+
+Create a file in `src/events/`. Set `once: true` if it should fire only once (e.g. `ready`).
+
+```js
+'use strict';
+
+const { Events } = require('discord.js');
+
+module.exports = {
+  name: Events.GuildMemberAdd,
+
+  async execute(client, member) {
+    console.log(`${member.user.tag} joined ${member.guild.name}`);
+  },
+};
+```
+
+---
+
+## Logging
+
+Log files are written to the `logs/` directory (git-ignored). The log level defaults to `info` and can be overridden with the `LOG_LEVEL` environment variable (e.g. `LOG_LEVEL=debug npm start`).
+