From fbc5c0533df34f11450650cf1e2b9ad565323c23 Mon Sep 17 00:00:00 2001 From: sirpiglr <49359077-sirpiglr@users.noreply.replit.com> Date: Mon, 8 Dec 2025 20:55:22 +0000 Subject: [PATCH] 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 --- .replit | 2 +- aethex-bot/docs/MANUAL.md | 667 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 668 insertions(+), 1 deletion(-) create mode 100644 aethex-bot/docs/MANUAL.md diff --git a/.replit b/.replit index 0e87d21..7cfa9d1 100644 --- a/.replit +++ b/.replit @@ -23,7 +23,7 @@ localPort = 8080 externalPort = 8080 [[ports]] -localPort = 32905 +localPort = 39769 externalPort = 3000 [workflows] diff --git a/aethex-bot/docs/MANUAL.md b/aethex-bot/docs/MANUAL.md new file mode 100644 index 0000000..d66b314 --- /dev/null +++ b/aethex-bot/docs/MANUAL.md @@ -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).*