AeThex-Bot-Master/aethex-bot/docs/MANUAL.md

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
2. Introduction
3. Getting Started
4. The AeThex Ecosystem
5. Community Features
6. XP & Leveling System
7. Moderation Tools
8. Auto-Moderation
9. Server Management
10. Security (Sentinel)
11. Admin Configuration
12. Command Reference
13. 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:

# 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 [category]

Category Options:

Option	Description
xp	All-time XP leaders (default)
weekly	This week's top earners
monthly	This month's top earners
posts	Most active posters
likes	Most liked users
creators	Top project creators

Weekly/Monthly Leaderboards:

• Track XP earned within the current period
• Reset automatically at the start of each week (Monday) or month
• Show messages count alongside XP earned
• Great for recurring engagement competitions!

Features:

• Medal rankings (🥇 🥈 🥉)
• XP totals and levels
• Automatic period resets

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!

Achievements

Create custom server achievements with various triggers:

/achievements create [name] [trigger] [value]

Available Triggers:

Trigger	Description
Level	Reach a specific level
Prestige	Reach a prestige level
Total XP	Earn total XP amount
Messages	Send X messages
Reactions Given	Give X reactions
Reactions Received	Receive X reactions
Voice Minutes	Spend X minutes in voice
Daily Streak	Achieve X day streak
Commands Used	Use X commands

Achievement Options:

• Icon: Custom emoji for the achievement
• Description: Custom description
• Reward XP: XP bonus when earned
• Reward Role: Role awarded when earned
• Hidden: Hide until earned (secret achievements)

Commands:

/achievements create [name] [trigger] [value]  # Create achievement
/achievements delete [name]                     # Delete achievement
/achievements list                              # View all server achievements
/achievements view [@user]                      # View earned achievements
/achievements grant @user [name]                # Manually grant achievement
/achievements revoke @user [name]               # Revoke achievement

XP Shop System

Spend your hard-earned XP on cosmetics, perks, and exclusive items!

User Commands:

/shop browse [category]   # Browse available items
/shop buy <item_id>       # Purchase an item
/shop inventory           # View your purchased items
/shop equip <item_id>     # Equip a badge, title, or background
/shop balance             # Check your XP balance

Item Categories:

Category	Description
🏅 Badges	Collectible profile badges
🏷️ Titles	Custom titles for your profile
🎨 Backgrounds	Profile card backgrounds
⚡ Boosters	Temporary XP multipliers
👑 Roles	Purchasable server roles
✨ Special	Limited edition items

How It Works:

• Your XP balance is based on your total earned XP minus what you've spent
• Purchasing an item deducts from your balance, not your level
• Some items may have level, prestige, or role requirements
• Limited stock items are first-come, first-served
• Boosters can be stacked and have expiration times

Admin Commands (shop-manage):

/shop-manage add [name] [price] [type]    # Add new item
/shop-manage edit <item_id> [options]     # Edit existing item
/shop-manage remove <item_id>             # Remove item from shop
/shop-manage list                         # List all items (admin view)
/shop-manage stats                        # View shop statistics

Adding Items:

• name: Item display name
• price: Cost in XP
• type: badge, title, background, booster, role, or special
• Optional: description, stock limit, level/prestige requirements
• For roles: specify grant_role to give users a role on purchase
• For boosters: set booster_multiplier and booster_hours

Quest System

Complete quests to earn bonus XP! Quests provide rotating objectives that keep engagement fresh.

User Commands:

/quests view [type]       # View available quests
/quests progress          # See your current progress
/quests claim [quest_id]  # Claim rewards for completed quests

Quest Types:

Type	Description
Daily	Reset every day, quick objectives
Weekly	Larger goals, higher rewards
Special	Limited-time events and challenges

Quest Objectives:

Objective	What to Do
messages	Send messages in the server
reactions	Add reactions to messages
voice_minutes	Spend time in voice channels
commands	Use bot commands
daily_claims	Claim daily rewards
level_ups	Level up your account
xp_earned	Earn XP from any source

How Quests Work:

1. View available quests with /quests view
2. Progress is tracked automatically as you participate
3. Check your progress with /quests progress
4. Once completed, claim your XP with /quests claim
5. Some quests may also grant roles as rewards!

Admin Commands (quests-manage):

/quests-manage create [name] [type] [objective] [target] [xp_reward]
/quests-manage edit <quest_id> [options]
/quests-manage delete <quest_id>
/quests-manage list
/quests-manage reset [quest_id] [type]
/quests-manage stats

Creating Quests:

• name: Quest display name
• type: daily, weekly, or special
• objective: What users need to do
• target: Amount needed to complete
• xp_reward: XP given on completion
• Optional: description, role_reward, duration_hours, repeatable

---

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 (5)

Command	Description
/rank	View your level and XP
/daily	Claim daily XP bonus
/badges	View earned badges
/prestige	Prestige system
/achievements	Achievement management

XP Shop Commands (2)

Command	Description
/shop browse/buy/inventory/equip/balance	XP shop for cosmetics and perks
/shop-manage add/edit/remove/list/stats	Admin shop management

Quest Commands (2)

Command	Description
/quests view/progress/claim	View and complete quests for XP
/quests-manage create/edit/delete/list/reset/stats	Admin quest management

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.