Add comprehensive guide for bot features and usage
Add a new manual documentation file (MANUAL.md) detailing bot features, prerequisites, and setup instructions. Replit-Commit-Author: Agent Replit-Commit-Session-Id: aed2e46d-25bb-4b73-81a1-bb9e8437c261 Replit-Commit-Checkpoint-Type: intermediate_checkpoint Replit-Commit-Event-Id: 8a63ea01-888e-4ba2-a228-372092576f9e Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/3bdfff67-975a-46ad-9845-fbb6b4a4c4b5/aed2e46d-25bb-4b73-81a1-bb9e8437c261/ZjyNKqu Replit-Helium-Checkpoint-Created: true
This commit is contained in:
sirpiglr
parent
7ba6e23d2d
commit
fbc5c0533d
2 changed files with 668 additions and 1 deletions
2
.replit
2
.replit
|
|
@ -23,7 +23,7 @@ localPort = 8080
|
|||
externalPort = 8080
|
||||
|
||||
[[ports]]
|
||||
localPort = 32905
|
||||
localPort = 39769
|
||||
externalPort = 3000
|
||||
|
||||
[workflows]
|
||||
|
|
|
|||
667
aethex-bot/docs/MANUAL.md
Normal file
667
aethex-bot/docs/MANUAL.md
Normal file
|
|
@ -0,0 +1,667 @@
|
|||
# AeThex Unified Bot Manual
|
||||
|
||||
> The complete guide to AeThex Bot - your all-in-one Discord companion for community management, engagement, and security.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#prerequisites)
|
||||
2. [Introduction](#introduction)
|
||||
3. [Getting Started](#getting-started)
|
||||
4. [The AeThex Ecosystem](#the-aethex-ecosystem)
|
||||
5. [Community Features](#community-features)
|
||||
6. [XP & Leveling System](#xp--leveling-system)
|
||||
7. [Moderation Tools](#moderation-tools)
|
||||
8. [Auto-Moderation](#auto-moderation)
|
||||
9. [Server Management](#server-management)
|
||||
10. [Security (Sentinel)](#security-sentinel)
|
||||
11. [Admin Configuration](#admin-configuration)
|
||||
12. [Command Reference](#command-reference)
|
||||
13. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Setup
|
||||
|
||||
Before using all features, ensure the following are configured:
|
||||
|
||||
| Requirement | Purpose | Without It |
|
||||
|-------------|---------|------------|
|
||||
| `DISCORD_BOT_TOKEN` | Bot authentication | Bot won't start |
|
||||
| `DISCORD_CLIENT_ID` | Slash command registration | Commands won't work |
|
||||
| `SUPABASE_URL` | Database connection | Limited features |
|
||||
| `SUPABASE_SERVICE_ROLE` | Database access | Limited features |
|
||||
|
||||
### Feature Availability
|
||||
|
||||
**With Supabase configured:**
|
||||
- Full XP and leveling system
|
||||
- User verification and profiles
|
||||
- Moderation logging
|
||||
- Server configurations (welcome, goodbye, etc.)
|
||||
- Role panels, giveaways, scheduled messages
|
||||
- Auto-moderation settings
|
||||
- Federation mappings and tickets
|
||||
|
||||
**Without Supabase:**
|
||||
- Basic moderation commands (no logging)
|
||||
- Sentinel anti-nuke protection (RAM-based)
|
||||
- Utility commands (userinfo, serverinfo, avatar)
|
||||
- Announcements and polls
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Set these in your Replit Secrets or `.env` file:
|
||||
|
||||
```env
|
||||
# Required
|
||||
DISCORD_BOT_TOKEN=your_bot_token
|
||||
DISCORD_CLIENT_ID=your_client_id
|
||||
|
||||
# Recommended
|
||||
SUPABASE_URL=your_supabase_url
|
||||
SUPABASE_SERVICE_ROLE=your_service_role_key
|
||||
|
||||
# Optional - Realm Guild IDs
|
||||
HUB_GUILD_ID=
|
||||
LABS_GUILD_ID=
|
||||
GAMEFORGE_GUILD_ID=
|
||||
CORP_GUILD_ID=
|
||||
FOUNDATION_GUILD_ID=
|
||||
|
||||
# Optional - Security
|
||||
WHITELISTED_USERS=user_id1,user_id2
|
||||
ALERT_CHANNEL_ID=channel_for_security_alerts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
### What is AeThex Bot?
|
||||
|
||||
AeThex Unified Bot is a powerful, all-in-one Discord bot designed specifically for the AeThex community ecosystem. It combines:
|
||||
|
||||
- **Community Features** - User verification, profile linking, and cross-platform integration
|
||||
- **Engagement Tools** - XP system, leveling, leaderboards, and achievements
|
||||
- **Moderation Suite** - Comprehensive moderation with logging and auto-mod
|
||||
- **Server Management** - Welcome messages, role panels, giveaways, and more
|
||||
- **Sentinel Security** - Enterprise-grade anti-nuke protection
|
||||
|
||||
### Key Features at a Glance
|
||||
|
||||
| Category | Features |
|
||||
|----------|----------|
|
||||
| Community | Profile linking, realm selection, cross-platform stats |
|
||||
| Engagement | XP tracking, daily claims, leaderboards, badges |
|
||||
| Moderation | Warn, kick, ban, timeout, mod logs, auto-mod |
|
||||
| Management | Welcome/goodbye, role panels, giveaways, announcements |
|
||||
| Security | Anti-nuke, heat tracking, federation sync |
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Linking Your Account
|
||||
|
||||
To get the full AeThex experience, link your Discord account to your AeThex profile:
|
||||
|
||||
```
|
||||
/verify
|
||||
```
|
||||
|
||||
This connects your Discord to your AeThex.studio or AeThex.foundation account, enabling:
|
||||
- Unified XP across all platforms
|
||||
- Cross-platform statistics
|
||||
- Special badges and rewards
|
||||
- Realm-specific features
|
||||
|
||||
### Setting Your Realm
|
||||
|
||||
AeThex has multiple realms (servers) for different purposes. Set your primary realm:
|
||||
|
||||
```
|
||||
/set-realm
|
||||
```
|
||||
|
||||
**Available Realms:**
|
||||
- **Hub** - Main community gathering place
|
||||
- **Labs** - Development and experiments
|
||||
- **GameForge** - Gaming community
|
||||
- **Corp** - Professional/business discussions
|
||||
- **Foundation** - Core community initiatives
|
||||
|
||||
### Viewing Your Profile
|
||||
|
||||
See your complete AeThex profile with stats, badges, and XP:
|
||||
|
||||
```
|
||||
/profile
|
||||
```
|
||||
|
||||
Your profile card shows:
|
||||
- Avatar and username
|
||||
- Current level and XP progress
|
||||
- XP bar with percentage
|
||||
- Platform badges
|
||||
- Account verification status
|
||||
|
||||
---
|
||||
|
||||
## The AeThex Ecosystem
|
||||
|
||||
### Cross-Platform Integration
|
||||
|
||||
AeThex Bot connects three platforms:
|
||||
|
||||
1. **Discord** - Real-time community chat
|
||||
2. **AeThex.studio** - Creative platform for projects
|
||||
3. **AeThex.foundation** - Community initiatives and contributions
|
||||
|
||||
XP earned on any platform contributes to your unified level!
|
||||
|
||||
### Federation System
|
||||
|
||||
The federation system allows roles to sync across multiple AeThex servers:
|
||||
|
||||
```
|
||||
/federation link @role # Link a role for cross-server sync
|
||||
/federation unlink @role # Remove a role from sync
|
||||
/federation list # View all linked roles
|
||||
```
|
||||
|
||||
This means if you earn a special role in one realm, it can automatically apply to others.
|
||||
|
||||
---
|
||||
|
||||
## Community Features
|
||||
|
||||
### Profile & Stats
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/profile` | View your profile card with XP bar and badges |
|
||||
| `/stats` | View detailed statistics |
|
||||
| `/rank` | Quick view of your level and XP |
|
||||
| `/badges` | View all earned badges |
|
||||
|
||||
### Leaderboards
|
||||
|
||||
See who's leading the community:
|
||||
|
||||
```
|
||||
/leaderboard
|
||||
```
|
||||
|
||||
Features:
|
||||
- Medal rankings (🥇 🥈 🥉)
|
||||
- XP totals and levels
|
||||
- Progress bars
|
||||
- Weekly/monthly views
|
||||
|
||||
### Community Posts
|
||||
|
||||
Share content with the community:
|
||||
|
||||
```
|
||||
/post
|
||||
```
|
||||
|
||||
Posts sync to the AeThex feed and can be viewed across platforms.
|
||||
|
||||
### Studio & Foundation
|
||||
|
||||
View platform-specific profiles:
|
||||
|
||||
```
|
||||
/studio [@user] # View AeThex Studio profile
|
||||
/foundation [@user] # View Foundation contributions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## XP & Leveling System
|
||||
|
||||
### How to Earn XP
|
||||
|
||||
| Activity | XP Earned | Cooldown |
|
||||
|----------|-----------|----------|
|
||||
| Send a message | +5 XP | 60 seconds |
|
||||
| Daily claim | +50 XP base | 24 hours |
|
||||
| Daily streak bonus | Up to +100 XP | Cumulative |
|
||||
| Platform activity | Varies | None |
|
||||
|
||||
### Daily Claims
|
||||
|
||||
Claim your daily XP bonus:
|
||||
|
||||
```
|
||||
/daily
|
||||
```
|
||||
|
||||
**Streak System:**
|
||||
- Day 1: +50 XP
|
||||
- Day 2: +55 XP
|
||||
- Day 3: +60 XP
|
||||
- ... up to Day 10+: +100 XP
|
||||
|
||||
Missing a day resets your streak!
|
||||
|
||||
### Leveling Formula
|
||||
|
||||
```
|
||||
Level = floor(sqrt(XP / 100))
|
||||
```
|
||||
|
||||
**XP Requirements:**
|
||||
| Level | Total XP Needed |
|
||||
|-------|-----------------|
|
||||
| 1 | 100 |
|
||||
| 2 | 400 |
|
||||
| 3 | 900 |
|
||||
| 5 | 2,500 |
|
||||
| 10 | 10,000 |
|
||||
| 20 | 40,000 |
|
||||
| 50 | 250,000 |
|
||||
|
||||
### Level Rewards
|
||||
|
||||
Admins can set automatic role rewards at certain levels. When you reach the required level, you automatically receive the role!
|
||||
|
||||
---
|
||||
|
||||
## Moderation Tools
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Command | Description | Permission |
|
||||
|---------|-------------|------------|
|
||||
| `/warn @user [reason]` | Issue a warning | Moderate Members |
|
||||
| `/kick @user [reason]` | Kick from server | Kick Members |
|
||||
| `/ban @user [reason]` | Ban from server | Ban Members |
|
||||
| `/timeout @user [minutes] [reason]` | Temporary mute | Moderate Members |
|
||||
|
||||
### Warnings
|
||||
|
||||
```
|
||||
/warn @user This is a warning
|
||||
```
|
||||
|
||||
Warnings are logged and accumulate. Use `/modlog @user` to view a user's history.
|
||||
|
||||
### Moderation Logs
|
||||
|
||||
View a user's complete moderation history:
|
||||
|
||||
```
|
||||
/modlog @user
|
||||
```
|
||||
|
||||
Shows all warnings, kicks, bans, and timeouts with:
|
||||
- Date and time
|
||||
- Reason
|
||||
- Moderator who took action
|
||||
|
||||
### Audit Log
|
||||
|
||||
View recent admin actions in the server:
|
||||
|
||||
```
|
||||
/auditlog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto-Moderation
|
||||
|
||||
### Overview
|
||||
|
||||
Auto-mod automatically detects and handles rule violations:
|
||||
|
||||
```
|
||||
/automod
|
||||
```
|
||||
|
||||
### Available Filters
|
||||
|
||||
| Filter | Description | Actions |
|
||||
|--------|-------------|---------|
|
||||
| **Links** | Block unauthorized URLs | Delete, warn, timeout |
|
||||
| **Spam** | Detect message flooding | Delete, warn, timeout |
|
||||
| **Bad Words** | Custom word blacklist | Delete, warn, timeout |
|
||||
| **Invites** | Block Discord invite links | Delete, warn |
|
||||
| **Mentions** | Limit mass mentions | Delete, warn |
|
||||
|
||||
### Configuration
|
||||
|
||||
```
|
||||
/automod links enable # Enable link filtering
|
||||
/automod spam threshold 5 # Set spam threshold
|
||||
/automod badwords add [word] # Add to blacklist
|
||||
/automod invites enable # Block invite links
|
||||
/automod mentions limit 5 # Limit mentions per message
|
||||
```
|
||||
|
||||
### Exempt Roles
|
||||
|
||||
Certain roles can be exempted from auto-mod:
|
||||
|
||||
```
|
||||
/automod exempt @Moderator
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server Management
|
||||
|
||||
### Welcome Messages
|
||||
|
||||
Greet new members with rich embeds:
|
||||
|
||||
```
|
||||
/config welcome #welcome-channel
|
||||
```
|
||||
|
||||
Welcome messages include:
|
||||
- Member's avatar
|
||||
- Personalized greeting
|
||||
- Server member count
|
||||
- Beautiful embed design
|
||||
|
||||
### Goodbye Messages
|
||||
|
||||
Bid farewell to departing members:
|
||||
|
||||
```
|
||||
/config goodbye #goodbye-channel
|
||||
```
|
||||
|
||||
### Auto-Role
|
||||
|
||||
Automatically assign a role to new members:
|
||||
|
||||
```
|
||||
/config autorole @Member
|
||||
```
|
||||
|
||||
### Role Panels
|
||||
|
||||
Create interactive role selection menus:
|
||||
|
||||
```
|
||||
/rolepanel
|
||||
```
|
||||
|
||||
Features:
|
||||
- Button-based role selection
|
||||
- Custom colors and descriptions
|
||||
- Multiple roles per panel
|
||||
- Persists after bot restart
|
||||
|
||||
### Announcements
|
||||
|
||||
Send beautiful announcements with templates:
|
||||
|
||||
```
|
||||
/announce [title] [message]
|
||||
```
|
||||
|
||||
**Templates Available:**
|
||||
| Type | Color | Use For |
|
||||
|------|-------|---------|
|
||||
| Update | Blue | New features, changes |
|
||||
| Event | Purple | Community events |
|
||||
| Important | Yellow | Critical notices |
|
||||
| Highlight | Green | Celebrations |
|
||||
| Warning | Orange | Alerts |
|
||||
| Maintenance | Gray | Downtime notices |
|
||||
|
||||
### Polls
|
||||
|
||||
Create community polls:
|
||||
|
||||
```
|
||||
/poll [question] [options]
|
||||
```
|
||||
|
||||
### Giveaways
|
||||
|
||||
Run automated giveaways:
|
||||
|
||||
```
|
||||
/giveaway create [prize] [duration] [winners]
|
||||
/giveaway end [message_id]
|
||||
/giveaway reroll [message_id]
|
||||
```
|
||||
|
||||
Features:
|
||||
- Automatic winner selection
|
||||
- Entry tracking
|
||||
- Optional role requirements
|
||||
- Reroll capability
|
||||
|
||||
### Scheduled Messages
|
||||
|
||||
Schedule announcements for later:
|
||||
|
||||
```
|
||||
/schedule [time] [channel] [message]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security (Sentinel)
|
||||
|
||||
### Anti-Nuke Protection
|
||||
|
||||
Sentinel monitors for destructive actions and automatically responds:
|
||||
|
||||
| Threat | Detection | Response |
|
||||
|--------|-----------|----------|
|
||||
| Mass channel deletion | 3+ in 10 seconds | Remove permissions, alert |
|
||||
| Mass role deletion | 3+ in 10 seconds | Remove permissions, alert |
|
||||
| Mass bans | 3+ in 10 seconds | Remove permissions, alert |
|
||||
| Mass kicks | 3+ in 10 seconds | Remove permissions, alert |
|
||||
|
||||
### Heat Tracking
|
||||
|
||||
Every user has a "heat" score that increases with suspicious activity:
|
||||
|
||||
```
|
||||
/admin heat @user
|
||||
```
|
||||
|
||||
- Heat accumulates with destructive actions
|
||||
- Heat decays over time
|
||||
- Exceeding threshold triggers automatic protection
|
||||
|
||||
### Threat Monitoring
|
||||
|
||||
View active threats:
|
||||
|
||||
```
|
||||
/admin threats
|
||||
```
|
||||
|
||||
### Whitelisted Users
|
||||
|
||||
Server owners can whitelist trusted users who bypass heat tracking:
|
||||
- Set via `WHITELISTED_USERS` environment variable
|
||||
- Comma-separated user IDs
|
||||
|
||||
### Tickets
|
||||
|
||||
Support ticket system for user assistance:
|
||||
|
||||
```
|
||||
/ticket create [reason] # Open a new ticket
|
||||
/ticket close # Close current ticket
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Admin Configuration
|
||||
|
||||
### Server Setup
|
||||
|
||||
Configure your server with `/config`:
|
||||
|
||||
| Setting | Command | Description |
|
||||
|---------|---------|-------------|
|
||||
| Welcome Channel | `/config welcome #channel` | Where welcome messages go |
|
||||
| Goodbye Channel | `/config goodbye #channel` | Where goodbye messages go |
|
||||
| Mod Log Channel | `/config modlog #channel` | Where mod actions are logged |
|
||||
| Level-Up Channel | `/config levelup #channel` | Where level-ups announce |
|
||||
| Auto-Role | `/config autorole @role` | Role given to new members |
|
||||
| Verified Role | `/config verified @role` | Role for verified users |
|
||||
| Level Roles | `/config levelrole @role [level]` | Automatic level rewards |
|
||||
|
||||
### View Current Config
|
||||
|
||||
```
|
||||
/config view
|
||||
```
|
||||
|
||||
### Admin Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/admin status` | Bot status and statistics |
|
||||
| `/admin servers` | View all connected servers |
|
||||
| `/admin heat @user` | Check user's heat level |
|
||||
| `/admin threats` | View active threat monitor |
|
||||
|
||||
### Custom Embeds
|
||||
|
||||
Create custom embeds with the modal builder:
|
||||
|
||||
```
|
||||
/embed
|
||||
```
|
||||
|
||||
Opens a form to set:
|
||||
- Title
|
||||
- Description
|
||||
- Color
|
||||
- Fields
|
||||
- Images
|
||||
- Footer
|
||||
- Target channel
|
||||
|
||||
---
|
||||
|
||||
## Command Reference
|
||||
|
||||
### Community Commands (10)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/verify` | Link your Discord account to AeThex |
|
||||
| `/unlink` | Disconnect your Discord from AeThex |
|
||||
| `/profile` | View your linked AeThex profile |
|
||||
| `/set-realm` | Choose your primary realm |
|
||||
| `/verify-role` | Check your assigned Discord roles |
|
||||
| `/refresh-roles` | Sync roles based on AeThex profile |
|
||||
| `/stats` | View your AeThex statistics |
|
||||
| `/leaderboard` | View top contributors |
|
||||
| `/post` | Create a community feed post |
|
||||
| `/help` | View categorized commands |
|
||||
|
||||
### Leveling Commands (3)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/rank` | View your level and XP |
|
||||
| `/daily` | Claim daily XP bonus |
|
||||
| `/badges` | View earned badges |
|
||||
|
||||
### Moderation Commands (5)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/warn @user [reason]` | Warn a user |
|
||||
| `/kick @user [reason]` | Kick a user |
|
||||
| `/ban @user [reason]` | Ban a user |
|
||||
| `/timeout @user [minutes] [reason]` | Timeout a user |
|
||||
| `/modlog @user` | View moderation history |
|
||||
|
||||
### Utility Commands (4)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/userinfo [@user]` | View user information |
|
||||
| `/serverinfo` | View server statistics |
|
||||
| `/avatar [@user]` | Get user's avatar |
|
||||
| `/embed` | Create custom embeds |
|
||||
|
||||
### Admin Commands (9)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config` | Server configuration |
|
||||
| `/announce` | Send announcements |
|
||||
| `/poll` | Create community poll |
|
||||
| `/auditlog` | View admin action history |
|
||||
| `/rolepanel` | Create role panels |
|
||||
| `/giveaway` | Giveaway management |
|
||||
| `/schedule` | Schedule messages |
|
||||
| `/automod` | Auto-moderation settings |
|
||||
| `/admin` | Bot administration |
|
||||
|
||||
### Cross-Platform Commands (2)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/studio [@user]` | View AeThex Studio profile |
|
||||
| `/foundation [@user]` | View Foundation contributions |
|
||||
|
||||
### Security Commands (4)
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/federation` | Federation role management |
|
||||
| `/ticket` | Support ticket system |
|
||||
| `/status` | View network status |
|
||||
| `/admin` | Security monitoring |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"You are not verified"**
|
||||
- Use `/verify` to link your AeThex account
|
||||
- Make sure you have an AeThex.studio or AeThex.foundation account
|
||||
|
||||
**"Permission denied"**
|
||||
- Check if you have the required Discord permissions
|
||||
- Some commands are admin-only
|
||||
|
||||
**"Command not responding"**
|
||||
- The bot may be restarting
|
||||
- Try again in a few seconds
|
||||
- Check `/status` for bot status
|
||||
|
||||
**"XP not updating"**
|
||||
- XP has a 60-second cooldown between messages
|
||||
- Make sure you're in an XP-enabled channel
|
||||
|
||||
**"Level-up not announced"**
|
||||
- Check if a level-up channel is configured
|
||||
- Use `/config view` to verify settings
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Use `/help` to see all available commands
|
||||
2. Create a support ticket with `/ticket create`
|
||||
3. Contact server administrators
|
||||
4. Visit AeThex.foundation for community support
|
||||
|
||||
---
|
||||
|
||||
## Version Information
|
||||
|
||||
- **Bot Version**: 2.0.0
|
||||
- **Commands**: 36 total
|
||||
- **Last Updated**: December 2024
|
||||
|
||||
---
|
||||
|
||||
*This manual is maintained by the AeThex team. For updates and more information, visit [AeThex.foundation](https://aethex.foundation).*
|
||||
Loading…
Reference in a new issue