docs: add per-cog README files for all 8 cogs

Generated comprehensive README documentation for each cog: - dashboard (EveDash): Web dashboard setup & commands - newhelpmenu: Components V2 help system - nexuscore: All-in-one management (tickets, mod, economy, etc.) - selfbotguard: 14-layer selfbot detection - serverwhitelist: Server join management - userslash: User-installable slash commands - voicemeister: Temporary voice channels - wormhole: Cross-server relay (100+ commands) Each README includes: features, installation, commands, data statement.
2026-05-14 20:38:04 +00:00
8 changed files with 696 additions and 0 deletions
--- a/dashboard/README.md
+++ b/dashboard/README.md
@ -0,0 +1,53 @@
+# EveDash
+
+A modern, self-contained web dashboard for Red-DiscordBot.
+
+## Features
+
+- **Discord OAuth2 Login** — Secure authentication via Discord
+- **Guild Management** — View and manage all guilds the bot is in
+- **Cog Control** — Load, unload, and reload cogs from the browser
+- **Command Toggles** — Enable/disable commands per-guild
+- **Real-Time WebSocket** — Live updates for messages, members, and events
+- **SDK for Cogs** — Any cog can register its own settings pages with just a few lines of code
+
+## Requirements
+
+- `aiohttp`
+- Red-DiscordBot >= 3.5.0
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs dashboard
+[p]load dashboard
+```
+
+## Setup
+
+```
+[p]evedash setup
+```
+
+Follow the interactive setup wizard to configure Discord OAuth2 credentials and server settings.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `[p]evedash` | Show dashboard status and URL |
+| `[p]evedash setup` | Interactive setup wizard |
+| `[p]evedash port <port>` | Set the web server port |
+| `[p]evedash host <host>` | Set the web server host/bind address |
+| `[p]evedash secret <secret>` | Set the Discord OAuth2 client secret |
+| `[p]evedash clientid <id>` | Set the Discord OAuth2 client ID |
+| `[p]evedash redirect <uri>` | Set the OAuth2 redirect URI |
+
+## Data Statement
+
+This cog stores Discord user IDs for authentication sessions and blacklist management. No message content is stored.
+
+## License
+
+MIT
--- a/newhelpmenu/README.md
+++ b/newhelpmenu/README.md
@ -0,0 +1,59 @@
+# NewHelpMenu
+
+Components V2 help menu + global embed/menu override for Red-DiscordBot.
+
+## Features
+
+- **Components V2 Help** — Replaces Red's entire help system with Discord's Components V2 (containers, sections, text displays, thumbnails, media galleries, separators)
+- **Global Embed Override** — Optionally converts ALL bot embeds and menus into Components V2 layouts
+- **Categories** — Group cogs into custom categories for organized help pages
+- **Accent Colours** — Customizable colour scheme per-server
+- **Layout Modes** — Multiple layout styles for help pages
+- **Paginated Navigation** — Interactive buttons for browsing commands
+- **Select Menus** — Quick-jump to any cog or command
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.21
+- Python >= 3.9
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs newhelpmenu
+[p]load newhelpmenu
+```
+
+> ⚠️ This cog replaces Red's built-in `help` command. The original is restored on unload.
+
+## Quick Start
+
+```
+[p]cv2 toggle          # Enable Components V2 (off by default)
+[p]cv2 settings        # View all current settings
+[p]cv2 color <hex>     # Set accent colour
+[p]cv2 category add <name> <cog1> <cog2>...  # Group cogs into categories
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `[p]cv2 toggle` | Enable/disable Components V2 mode |
+| `[p]cv2 settings` | View current configuration |
+| `[p]cv2 color <hex>` | Set accent colour |
+| `[p]cv2 category add <name> <cogs...>` | Create a cog category |
+| `[p]cv2 category remove <name>` | Remove a category |
+| `[p]cv2 category list` | List all categories |
+| `[p]help` | Show the help menu (replaced) |
+| `[p]help <command>` | Show help for a specific command |
+| `[p]help <cog>` | Show help for a specific cog |
+
+## Data Statement
+
+This cog stores per-guild configuration. No personal user data is stored.
+
+## License
+
+MIT
--- a/nexuscore/README.md
+++ b/nexuscore/README.md
@ -0,0 +1,93 @@
+# NexusCore v2.0.0
+
+The ultimate all-in-one server management cog for Red-DiscordBot. 10 modules, 100+ commands.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| 🎫 **Tickets** | Panel-based creation, categories, custom questions, staff claim, priority levels, HTML transcripts, auto-close, feedback |
+| 📝 **Applications** | Multi-type forms, multi-page modals (10+ questions), review system, auto-role, staff notes, cooldowns |
+| 💡 **Suggestions** | Voting, 10 status types, anonymous mode, auto-thread, staff responses, categories, leaderboard |
+| 🎭 **Reaction Roles** | Button/select/reaction modes, exclusive groups, sticky/temp roles, max picks, persistent |
+| 🎉 **Giveaways** | Button-entry, role requirements, bonus entries, drop mode, recurring, DM notifications |
+| 📋 **Server Logging** | 30+ event types, per-event routing, message cache, invite tracking, ignore filters |
+| 🛡️ **Moderation** | Case system, warnings with auto-escalation, quarantine, reputation, appeal system, anti-raid/nuke |
+| 💰 **Economy** | Wallet/bank, daily/weekly, work/crime, gambling (coinflip/slots/blackjack/roulette/dice), shop, pets, heist, auction house |
+| 🎨 **Embed Builder** | Webhook-based, Sapphire-style, templates, scheduling, variables |
+| 📊 **Dashboard** | Web config integration for all modules (requires EveDash) |
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.0
+- Python >= 3.9
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs nexuscore
+[p]load nexuscore
+```
+
+## Quick Start
+
+```
+[p]nexus                        # Module overview & version
+[p]ticket setup #category #logs # Set up tickets
+[p]apply setup #review          # Set up applications
+[p]suggest setup #suggestions   # Set up suggestions
+[p]roles create #channel button Title  # Create a role panel
+[p]gw start #channel 1d 1 Prize       # Start a giveaway
+[p]serverlog enable #logs       # Enable logging (30+ events)
+[p]nmod setup #modlog           # Set up moderation
+[p]eco balance                  # Check economy balance
+[p]eb create                    # Interactive embed builder
+```
+
+## Key Commands
+
+### Tickets
+| Command | Description |
+|---------|-------------|
+| `[p]ticket setup <category> <log_channel>` | Set up the ticket system |
+| `[p]ticket panel <channel>` | Send a ticket creation panel |
+| `[p]ticket close [reason]` | Close a ticket |
+| `[p]ticket add/remove <user>` | Add/remove user from ticket |
+| `[p]ticket claim` | Claim a ticket as staff |
+| `[p]ticket priority <level>` | Set ticket priority |
+| `[p]ticket transcript` | Export HTML transcript |
+
+### Moderation
+| Command | Description |
+|---------|-------------|
+| `[p]nmod setup <modlog>` | Set up moderation |
+| `[p]nmod warn <user> [reason]` | Warn a user (auto-escalates) |
+| `[p]nmod mute/unmute <user>` | Mute/unmute |
+| `[p]nmod kick/ban <user>` | Kick/ban |
+| `[p]nmod case <id>` | View a case |
+| `[p]nmod history <user>` | User's moderation history |
+| `[p]nmod quarantine <user>` | Quarantine a user |
+| `[p]nmod lockdown` | Lock the server |
+
+### Economy
+| Command | Description |
+|---------|-------------|
+| `[p]eco balance` | Check balance |
+| `[p]eco daily / weekly` | Claim rewards |
+| `[p]eco work / crime` | Earn money |
+| `[p]eco coinflip / slots / blackjack` | Gamble |
+| `[p]eco shop / buy / inventory` | Shop system |
+| `[p]eco pet adopt <type>` | Adopt a pet |
+| `[p]eco heist <amount>` | Start a multiplayer heist |
+| `[p]eco leaderboard` | View rankings |
+
+*Full command reference: `[p]help NexusCore`*
+
+## Data Statement
+
+This cog stores Discord user IDs, guild IDs, and channel IDs. Per-user data includes: ticket history, application submissions, suggestion authorship, moderation cases/warnings/notes, economy balances/inventories/pets/transactions, giveaway entries, and reaction role state.
+
+## License
+
+MIT
--- a/selfbotguard/README.md
+++ b/selfbotguard/README.md
@ -0,0 +1,74 @@
+# SelfbotGuard v1.2.0
+
+Advanced selfbot detection with 14 heuristic layers and configurable per-server punishments for Red-DiscordBot.
+
+## Detection Layers
+
+| # | Heuristic | What it detects |
+|---|-----------|-----------------|
+| 1 | Rich-embed abuse | Selfbots sending embeds (regular users can't) |
+| 2 | Inhuman response time | Replies faster than humanly possible |
+| 3 | Timing precision | Unnaturally consistent message intervals |
+| 4 | 24/7 activity | No sleep/break patterns |
+| 5 | Pattern matching | Automated command-response sequences |
+| 6 | Burst detection | Rapid-fire message floods |
+| 7 | Cross-channel spam | Same message blasted across channels |
+| 8 | Cross-server activity | Messages in different servers within impossible windows |
+| 9 | Edit cadence | Suspiciously regular edit timing |
+| 10 | Presence anomalies | Messaging while offline/invisible |
+| 11 | Reaction sniping | Reacting inhumanly fast (giveaway sniping) |
+| 12 | Formatting analysis | Suspiciously clean formatting at speed |
+| 13 | Trigger-word sniping | Instant response to giveaway/nitro keywords |
+| 14 | Self-delete patterns | Automated self-deletion behaviour |
+
+Each heuristic contributes to a cumulative suspicion score per user. When the score exceeds the configurable threshold, action is taken.
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.0
+- Python >= 3.9
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs selfbotguard
+[p]load selfbotguard
+```
+
+> ⚠️ The cog is **disabled by default** — enable per-server with `[p]sbguard enable`.
+
+## Commands
+
+### Prefix Commands (`[p]sbguard`)
+| Command | Description |
+|---------|-------------|
+| `[p]sbguard enable` | Enable detection in this server |
+| `[p]sbguard disable` | Disable detection |
+| `[p]sbguard action <action>` | Set punishment: `warn`, `mute`, `kick`, `ban`, `log` |
+| `[p]sbguard sensitivity <level>` | Set sensitivity: `low`, `medium`, `high`, `paranoid` |
+| `[p]sbguard threshold <number>` | Set custom suspicion threshold |
+| `[p]sbguard logchannel <#channel>` | Set the alert/log channel |
+| `[p]sbguard muteduration <time>` | Set mute/timeout duration |
+| `[p]sbguard exempt <@role>` | Exempt a role from detection |
+| `[p]sbguard unexempt <@role>` | Remove exemption |
+| `[p]sbguard notifystaff <on/off>` | Toggle staff DM notifications |
+| `[p]sbguard settings` | View current configuration |
+| `[p]sbguard flagged` | View flagged/suspected users |
+| `[p]sbguard unflag <@user>` | Clear a user's suspicion score |
+| `[p]sbguard scan <@user>` | Manually scan a specific user |
+| `[p]sbguard reset` | Reset all detection data for this server |
+
+### Slash Commands
+| Command | Description |
+|---------|-------------|
+| `/sbguard-status` | Check SelfbotGuard status (admin only) |
+| `/sbguard-scan <user>` | Scan a user for selfbot indicators (admin only) |
+
+## Data Statement
+
+This cog stores Discord user IDs and guild IDs for selfbot detection. Per-user data includes message timestamps, response timing, activity windows, and suspicion scores. Data is periodically pruned.
+
+## License
+
+MIT
--- a/serverwhitelist/README.md
+++ b/serverwhitelist/README.md
@ -0,0 +1,84 @@
+# ServerWhitelist v4.0
+
+The ultimate owner-only server management cog for Red-DiscordBot. Complete control over which Discord servers the bot can operate in.
+
+## Features
+
+- **Whitelist / Blacklist** — Approve or block servers with paginated views
+- **Interactive Browser** — Browse all servers with leave dropdowns
+- **Whitelist Requests** — Server owners can request access via DM button; you approve/deny
+- **Notes & Tags** — Annotate and categorize servers for organization
+- **Invite Audit** — See who added the bot via Discord audit log
+- **Temp Whitelist** — Time-limited server access (e.g., `[p]join temp <id> 7d`)
+- **Member Requirements** — Min/max member thresholds for auto-approval
+- **Trusted Inviters** — Auto-whitelist when specific users add the bot
+- **Owner Alerts** — DM notifications for all join/leave events
+- **Auto-Ban** — Configurable threshold for repeated unauthorized join attempts
+- **Backup & Restore** — Full config export/import
+- **Rich Logging** — Colour-coded event logging to a dedicated channel
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.0
+- Python >= 3.9
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs serverwhitelist
+[p]load serverwhitelist
+```
+
+> All servers the bot is currently in are automatically whitelisted on first load.
+
+## Commands (Owner Only)
+
+### Core
+| Command | Description |
+|---------|-------------|
+| `[p]join <id>` | Whitelist a server |
+| `[p]join remove <id>` | Remove from whitelist |
+| `[p]join whitelist` | View the whitelist |
+| `[p]join blacklist <id>` | Blacklist a server |
+| `[p]join unblacklist <id>` | Remove from blacklist |
+| `[p]join blacklisted` | View the blacklist |
+
+### Management
+| Command | Description |
+|---------|-------------|
+| `[p]join servers` | Interactive server browser with leave controls |
+| `[p]join info <id>` | Detailed server info embed |
+| `[p]join search <query>` | Search servers by name |
+| `[p]join stats` | Overview statistics |
+| `[p]join leave <id>` | Force-leave a server |
+| `[p]join purge` | Leave all non-whitelisted servers |
+| `[p]join lock / unlock` | Lock mode (reject all new joins) |
+
+### Configuration
+| Command | Description |
+|---------|-------------|
+| `[p]join log <#channel>` | Set event logging channel |
+| `[p]join settings` | View all settings |
+| `[p]join export` | Export full config |
+| `[p]join attempts` | View unauthorized join attempts |
+| `[p]join attempts reset` | Reset attempt counters |
+
+### v4.0 Features
+| Command | Description |
+|---------|-------------|
+| `[p]join temp <id> <duration>` | Temporary whitelist |
+| `[p]join note <id> <text>` | Add a note to a server |
+| `[p]join tag <id> <tag>` | Tag a server for organization |
+| `[p]join trusted add/remove <@user>` | Manage trusted inviters |
+| `[p]join minmembers / maxmembers` | Set member requirements |
+| `[p]join alerts on/off` | Toggle owner DM alerts |
+| `[p]join backup / restore` | Backup and restore config |
+
+## Data Statement
+
+This cog stores guild IDs in a global whitelist, blacklist, join-attempt tracker, notes, tags, and whitelist request queue. No per-user data is collected beyond requester IDs in the request queue.
+
+## License
+
+MIT
--- a/userslash/README.md
+++ b/userslash/README.md
@ -0,0 +1,84 @@
+# UserSlash
+
+User-installable slash commands for Red-DiscordBot — every Red command works in servers, DMs, and group DMs.
+
+## What It Does
+
+UserSlash registers a single proxy slash command (named after the bot) that bridges *every* Red text command through Discord's slash-command interface. After syncing, all global commands are automatically patched with user-install integration types so the bot works as a user-installable app.
+
+Commands work everywhere:
+- ✅ Guild channels (where the bot is a member)
+- ✅ Bot DMs
+- ✅ Group DMs
+- ✅ Servers where the bot *isn't* a member (via user-install)
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.0
+- Python >= 3.9
+- `rapidfuzz` (auto-installed)
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs userslash
+[p]load userslash
+```
+
+> ⚠️ **Unload OneTrueSlash first** if you have it loaded — this cog replaces it.
+
+## Setup (One-Time)
+
+1. Go to the **Discord Developer Portal** → Your Application → **Installation**
+2. Under *Installation Contexts*, enable **User Install**
+3. Under *Default Install Settings — User Install*, add the `applications.commands` scope
+4. Run `[p]userslash sync` to register & patch commands
+5. Share the OAuth2 User-Install link so users can add your bot to their profile
+
+## Commands (Owner Only)
+
+| Command | Description |
+|---------|-------------|
+| `[p]userslash sync` | Sync the command tree + patch every command for user-install |
+| `[p]userslash patch` | Patch already-synced commands with user-install flags (no full sync) |
+| `[p]userslash status` | Show per-command user-install status (✅/⚠️) |
+
+### Whitelist
+| Command | Description |
+|---------|-------------|
+| `[p]userslash whitelist enable` | Restrict user-install to whitelisted users only |
+| `[p]userslash whitelist disable` | Allow anyone to use user-install |
+| `[p]userslash whitelist add <@users>` | Add users to the whitelist |
+| `[p]userslash whitelist remove <@users>` | Remove users from the whitelist |
+| `[p]userslash whitelist list` | View whitelist status and members |
+| `[p]userslash whitelist clear` | Clear the entire whitelist |
+
+## Architecture
+
+```
+userslash/
+├── __init__.py       # Cog class, lifecycle, owner commands, whitelist
+├── slash_bridge.py   # Proxy slash command, autocomplete, error handler
+├── patcher.py        # REST API patcher for user-install flags
+├── context.py        # InterContext — adapted Context for interactions
+├── channel.py        # Fake channel for DM/group-DM contexts
+├── message.py        # Synthetic Message for interaction contexts
+└── utils.py          # Name validation helpers
+```
+
+## How It Works
+
+1. On load, registers `/<botname>` as a global slash command with `integration_types: [0, 1]` (guild + user install)
+2. The slash command accepts a `command` parameter with fuzzy autocomplete
+3. When invoked, it finds the matching Red text command and executes it through Red's command system
+4. `InterContext` wraps the interaction to look like a regular `commands.Context`
+5. `patch_all_commands` hits the Discord REST API to add user-install flags to every registered command
+
+## Data Statement
+
+This cog does not persistently store any data or metadata about users.
+
+## License
+
+MIT
--- a/voicemeister/README.md
+++ b/voicemeister/README.md
@ -0,0 +1,95 @@
+# VoiceMeister v1.0.0
+
+The ultimate temporary voice channel system for Red-DiscordBot — Join-to-Create, full button control panel, name templates, game detection, and more.
+
+## Features
+
+- **Join-to-Create** — Users join a designated channel and a personal voice channel is auto-created
+- **Control Panel** — Persistent button panel with 17 actions (Lock, Unlock, Hide, Rename, Kick, Ban, etc.)
+- **Name Templates** — `{user}`, `{game}`, `{count}`, `{custom}` variables
+- **Game Detection** — Channels auto-rename based on the owner's current game activity
+- **Auto-Cleanup** — Channels are deleted when everyone leaves
+- **Blacklist / Whitelist** — Control who can create channels
+- **Persistent Views** — All buttons survive bot restarts
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.0
+- Python >= 3.9
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs voicemeister
+[p]load voicemeister
+```
+
+## Quick Start
+
+```
+[p]voicemeister setup              # Interactive setup wizard
+[p]voicemeister creator add #vc    # Add a Join-to-Create channel
+[p]voicemeister panel #channel     # Send the control panel
+```
+
+## Commands
+
+### Admin Commands (`[p]voicemeister` / `[p]vm`)
+| Command | Description |
+|---------|-------------|
+| `[p]vm setup` | Interactive setup wizard |
+| `[p]vm panel <#channel>` | Send the button control panel |
+| `[p]vm settings` | View current configuration |
+| `[p]vm logchannel <#channel>` | Set logging channel |
+| `[p]vm defaultname <template>` | Set default channel name template |
+| `[p]vm defaultlimit <number>` | Set default user limit |
+| `[p]vm defaultbitrate <kbps>` | Set default bitrate |
+| `[p]vm cooldown <seconds>` | Set creation cooldown |
+| `[p]vm maxchannels <number>` | Max temp channels per user |
+| `[p]vm gamerename <on/off>` | Toggle game activity renaming |
+| `[p]vm resetall` | Reset all VoiceMeister data |
+
+### Creator Management (`[p]vm creator` / `[p]vm jtc`)
+| Command | Description |
+|---------|-------------|
+| `[p]vm creator add <#vc>` | Add a Join-to-Create channel |
+| `[p]vm creator remove <#vc>` | Remove a JTC channel |
+| `[p]vm creator list` | List all JTC channels |
+| `[p]vm creator template <#vc> <name>` | Set per-creator name template |
+| `[p]vm creator userlimit <#vc> <n>` | Set per-creator user limit |
+| `[p]vm creator bitrate <#vc> <kbps>` | Set per-creator bitrate |
+
+### Blacklist / Whitelist
+| Command | Description |
+|---------|-------------|
+| `[p]vm blacklist add/remove/list` | Manage blacklisted users |
+| `[p]vm whitelist add/remove/list` | Manage whitelisted users |
+
+### User Commands (`[p]vc`)
+| Command | Description |
+|---------|-------------|
+| `[p]vc lock / unlock` | Lock/unlock your channel |
+| `[p]vc hide / unhide` | Hide/unhide your channel |
+| `[p]vc rename <name>` | Rename your channel |
+| `[p]vc limit <number>` | Set user limit |
+| `[p]vc permit / reject <@user>` | Allow/deny a user |
+| `[p]vc kick / ban <@user>` | Kick/ban a user from your channel |
+| `[p]vc claim` | Claim an ownerless channel |
+| `[p]vc transfer <@user>` | Transfer ownership |
+| `[p]vc bitrate <kbps>` | Set bitrate |
+| `[p]vc info` | Channel info & stats |
+| `[p]vc ghost` | Hide + lock (go invisible) |
+| `[p]vc delete` | Delete your channel |
+
+### Control Panel Buttons
+
+The persistent panel provides one-click access to: Lock, Unlock, Hide, Unhide, Ghost, Reveal, Rename, User Limit, Bitrate, Region, Permit, Reject, Kick, Ban, Mute All, Unmute All, Claim, Transfer, Info, and Delete.
+
+## Data Statement
+
+This cog stores Discord user IDs, guild IDs, and channel IDs for voice channel ownership and settings. Per-user data includes channel ownership, ban/permit lists, and usage cooldowns. Data is cleaned up when channels are deleted.
+
+## License
+
+MIT
--- a/wormhole/README.md
+++ b/wormhole/README.md
@ -0,0 +1,154 @@
+# Wormhole v4.0.0
+
+The ultimate cross-server message relay for Red-DiscordBot — modular architecture, hierarchical staff system, 100+ hybrid commands.
+
+## Features
+
+| Category | Features |
+|----------|----------|
+| **Relay** | Webhook / embed / compact modes, edit & delete sync, reply threading, sticker forwarding, pin sync, typing indicators, file relay |
+| **DM Relay** | Bidirectional DM ↔ network messaging, quiet hours, personal ignore lists |
+| **Moderation** | Ban/mute users & servers, word + regex filters, attachment filters, global blocklist, purge, network-wide edit & delete |
+| **Auto-Mod** | Anti-spam, anti-raid, anti-caps, anti-invite, anti-link, anti-zalgo, anti-spoiler, anti-emote-spam, anti-newlines |
+| **Staff System** | Hierarchical roles: Owner → Admin → Moderator → Helper → Member |
+| **Mentions** | Per-network + per-server policy for @user, @role, @everyone, @here with per-user exemptions |
+| **ToS/Rules** | Acceptance gate, legal template, consent tracking with timestamps, force re-accept |
+| **Reports** | Report via command or context menu, staff review, resolve, action (ban/mute/warn/dismiss) |
+| **Context Menus** | Report to Wormhole, Bookmark, Delete (staff), Profile — right-click actions |
+| **Social** | Karma/reputation, starboard, user profiles, keyword highlights |
+| **Invites** | Invite codes, vanity URLs, expiry, max uses, allowlists |
+| **Scheduling** | Scheduled messages, blackout windows, relay delay, slowmode |
+| **Advanced** | Anonymous mode, mirror channels, polls, AFK, auto-responses, ephemeral messages, media-only, analytics, health monitor, bookmarks, user colours, quiet hours, network bridging |
+
+## Requirements
+
+- Red-DiscordBot >= 3.5.0
+- Python >= 3.9
+
+## Installation
+
+```
+[p]repo add EveCogs https://github.com/everestmcarthur/EveCogs
+[p]cog install EveCogs wormhole
+[p]load wormhole
+```
+
+## Quick Start
+
+```
+[p]wh create <network-name>     # Create a new network
+[p]wh open <network-name>       # Link current channel to a network
+[p]wh close                     # Unlink current channel
+[p]wh list                      # List all networks
+```
+
+## Command Reference (100+ commands)
+
+### Core
+| Command | Description |
+|---------|-------------|
+| `[p]wh create <name>` | Create a new network |
+| `[p]wh delete <name>` | Delete a network |
+| `[p]wh open <name>` | Link current channel |
+| `[p]wh close` | Unlink current channel |
+| `[p]wh list` | List all networks |
+| `[p]wh info <name>` | Network info & stats |
+| `[p]wh portal [name]` | Create/refresh portal embed |
+
+### Settings (`[p]wh set`)
+| Command | Description |
+|---------|-------------|
+| `set mode` | Relay mode (webhook/embed/compact) |
+| `set colour / icon / description` | Network identity |
+| `set freeze / silent / nsfw-gate` | Toggles |
+| `set ratelimit / slowmode / relay-delay` | Flow control |
+| `set anonymous / ephemeral / media-only` | Special modes |
+| `set sync-*` | Toggle sync for edit/delete/reaction/reply/sticker/thread/pin/typing |
+
+### Mentions (`[p]wh mentions`)
+| Command | Description |
+|---------|-------------|
+| `mentions set <name> <type> <bool>` | Network-wide policy |
+| `mentions server-set <name> <type> <bool>` | Per-server override |
+| `mentions exempt / unexempt <name> @user` | Per-user exemptions |
+| `mentions status <name>` | View current policy |
+
+### Terms of Service (`[p]wh tos`)
+| Command | Description |
+|---------|-------------|
+| `tos enable / disable <name>` | Toggle ToS requirement |
+| `tos set <name> <text>` | Custom ToS text |
+| `tos template <name>` | Reset to legal template |
+| `tos accepted <name>` | View who accepted |
+| `tos reset <name>` | Force re-accept |
+
+### Reports (`[p]wh report`)
+| Command | Description |
+|---------|-------------|
+| `report message [msg_id] [reason]` | Report a message |
+| `report list <name>` | View reports (staff) |
+| `report resolve / action <name> <id>` | Handle reports |
+
+### Moderation (`[p]wh mod`)
+| Command | Description |
+|---------|-------------|
+| `mod ban / unban / mute / unmute` | User moderation |
+| `mod ban-server / unban-server` | Server moderation |
+| `mod edit <name> <msg_id> <text>` | Edit across entire network |
+| `mod nuke <name> <msg_id>` | Delete from entire network |
+| `mod purge <name> [count]` | Purge relayed messages |
+
+### Staff (`[p]wh staff`)
+| Command | Description |
+|---------|-------------|
+| `staff add / remove <name> <@user> <role>` | Manage staff |
+| `staff list <name>` | View staff roster |
+| `staff transfer <name> <@user>` | Transfer ownership |
+
+*See `[p]wh help` for the full interactive reference including DM relay, invites, filters, automod, social, scheduling, and advanced features.*
+
+## Architecture (v4.0.0)
+
+```
+wormhole/
+├── __init__.py          # Entry point
+├── core.py              # Main cog class, config, internal helpers
+├── wormhole.py          # Command definitions (100+ commands)
+├── utils.py             # Embeds, filters, automod, mention policy, helpers
+├── commands/            # Modular command mixins
+│   ├── _base.py         # Base mixin
+│   ├── network.py       # Network management
+│   ├── settings.py      # Settings commands
+│   ├── moderation.py    # Mod tools
+│   ├── filters.py       # Word/regex filters
+│   ├── mentions.py      # Mention policy
+│   ├── tos.py           # Terms of service
+│   ├── reports.py       # Report system
+│   ├── staff.py         # Staff management
+│   ├── social.py        # Karma, starboard, highlights
+│   ├── dm.py            # DM relay
+│   ├── bridge.py        # Network bridging
+│   ├── advanced.py      # Polls, AFK, auto-responses, analytics
+│   └── debug.py         # Debug commands
+├── listeners/           # Event listeners
+│   ├── relay.py         # Message relay pipeline
+│   ├── sync.py          # Edit/delete/reaction sync
+│   └── misc.py          # Guild join/leave
+├── models/              # Data models
+│   ├── config.py        # Config defaults
+│   ├── message_map.py   # Cross-server message ID mapping
+│   └── permissions.py   # Hierarchical role system
+├── services/
+│   └── emoji.py         # Foreign emoji resolution
+└── ui/
+    ├── modals.py        # Report modal
+    └── views.py         # Reply jump buttons
+```
+
+## Data Statement
+
+This cog stores Discord user IDs, guild IDs, and channel IDs for relay functionality. Per-user data includes message counts, karma scores, keyword highlights, DM relay subscriptions, bookmarks, AFK status, and more.
+
+## License
+
+MIT