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](#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 [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](https://aethex.foundation).*