commit, am too tired to add docs here

config/guilds/example-guild-123456789.yml

@@ -0,0 +1,149 @@
+# Example Guild Configuration
+# Copy this file to guild-{YOUR_GUILD_ID}.yml and customize
+
+# Basic Guild Information
+guild_id: 123456789012345678        # Replace with your Discord server ID
+name: "Example Gaming Community"    # Your server name
+owner_id: 987654321098765432        # Guild owner's Discord user ID
+premium: false                      # Set to true if you have premium features
+
+settings:
+  # General Settings
+  general:
+    prefix: "!"                     # Command prefix (for read-only commands)
+    locale: "en"                    # Language code
+    
+  # Discord Channel Configuration (use actual channel IDs or null)
+  channels:
+    log_channel_id: null            # General event logging
+    mod_log_channel_id: 888999000111222333    # Moderation action logging
+    welcome_channel_id: null        # New member welcome messages
+    
+  # Discord Role Configuration (use actual role IDs or null)
+  roles:
+    mute_role_id: 444555666777888999          # Role for timed-out members
+    verified_role_id: 111222333444555666      # Role given after verification
+    mod_role_ids:                             # List of moderator role IDs
+      - 777888999000111222
+      - 333444555666777888
+      
+  # Moderation System Configuration
+  moderation:
+    automod_enabled: true           # Enable automatic moderation
+    anti_spam_enabled: true         # Enable anti-spam protection
+    link_filter_enabled: true       # Enable suspicious link detection
+    
+    # Strike System - Actions at different strike thresholds
+    strike_actions:
+      "1":                          # At 1 strike: warn user
+        action: warn
+      "3":                          # At 3 strikes: 1 hour timeout
+        action: timeout
+        duration: 3600
+      "5":                          # At 5 strikes: kick from server
+        action: kick
+      "7":                          # At 7 strikes: ban from server
+        action: ban
+        
+  # Automatic Moderation Thresholds
+  automod:
+    # Message Rate Limiting
+    message_rate_limit: 5           # Max messages per time window
+    message_rate_window: 5          # Time window in seconds
+    duplicate_threshold: 3          # Duplicate messages to trigger action
+    
+    # Mention Spam Protection
+    mention_limit: 5                # Max mentions per single message
+    mention_rate_limit: 10          # Max mentions per time window
+    mention_rate_window: 60         # Mention time window in seconds
+    
+    # Scam Protection - Domains that bypass scam detection
+    scam_allowlist:
+      - "discord.com"               # Official Discord
+      - "github.com"                # Code repositories
+      - "youtube.com"               # Video platform
+      - "imgur.com"                 # Image hosting
+      - "steam.com"                 # Gaming platform
+      # Add your trusted domains here
+      
+  # AI-Powered Content Moderation
+  ai_moderation:
+    enabled: true                   # Enable AI content analysis
+    sensitivity: 75                 # AI sensitivity (0-100, higher = stricter)
+    confidence_threshold: 0.7       # Minimum confidence to take action (0.0-1.0)
+    log_only: false                 # Only log violations vs take action
+    nsfw_detection_enabled: true    # Enable NSFW image detection
+    
+    # NSFW-Only Filtering Mode (NEW FEATURE!)
+    nsfw_only_filtering: true       # true = Only block sexual content
+                                   # false = Block all inappropriate content
+    
+  # Member Verification System  
+  verification:
+    enabled: false                  # Enable verification for new members
+    type: "captcha"                 # Verification type: button, captcha, math, emoji
+
+# Guild-Specific Banned Words (optional)
+# These are in addition to patterns in config/wordlists/banned-words.yml
+banned_words:
+  - pattern: "guild-specific-word"
+    action: delete
+    is_regex: false
+    reason: "Server-specific rule"
+    category: harassment
+    
+  - pattern: "sp[a4]m.*bot"
+    action: timeout
+    is_regex: true                  # This is a regex pattern
+    reason: "Spam bot detection"
+    category: spam
+
+# Configuration Notes and Examples:
+#
+# === NSFW-ONLY FILTERING EXPLAINED ===
+# This is perfect for gaming communities that discuss violence but want to block sexual content:
+#
+# nsfw_only_filtering: true
+#   ✅ BLOCKS: Sexual content, nude images, explicit material
+#   ❌ ALLOWS: Violence, gore, harassment, hate speech, self-harm discussions
+#   
+# nsfw_only_filtering: false  
+#   ✅ BLOCKS: All inappropriate content (sexual, violence, harassment, hate speech, etc.)
+#
+# === AI SENSITIVITY GUIDE ===
+#   0-30   = Very lenient (only extreme violations)
+#   31-50  = Lenient (clear violations only)
+#   51-70  = Balanced (moderate detection) - RECOMMENDED
+#   71-85  = Strict (catches most potential issues) 
+#   86-100 = Very strict (may have false positives)
+#
+# === VERIFICATION TYPES ===
+#   button  = Simple button click (easiest for users)
+#   captcha = Text-based captcha entry (more secure)
+#   math    = Solve simple math problem (educational)
+#   emoji   = Select correct emoji from options (fun)
+#
+# === AUTOMOD ACTIONS ===
+#   warn    = Send warning message to user
+#   delete  = Delete the offending message
+#   timeout = Temporarily mute user (requires duration)
+#   kick    = Remove user from server (can rejoin)
+#   ban     = Permanently ban user from server
+#
+# === CONFIGURATION TIPS ===
+# 1. Start with balanced settings and adjust based on your community
+# 2. Use nsfw_only_filtering: true for gaming/mature discussion servers
+# 3. Set higher sensitivity (80+) for family-friendly servers
+# 4. Test settings with !ai analyze "test message" command
+# 5. Monitor mod logs to tune your settings
+# 6. Back up your config: python -m guardden.cli.config guild backup {guild_id}
+#
+# === HOT-RELOAD TESTING ===
+# Edit this file and save - changes apply within seconds!
+# Watch the bot logs to see configuration reload messages.
+# Use "!config" in Discord to verify your settings loaded correctly.
+#
+# === GETTING HELP ===
+# Run: python -m guardden.cli.config --help
+# Validate: python -m guardden.cli.config guild validate {guild_id}
+# Check status: python -m guardden.cli.config guild list

config/schemas/guild-schema.yml

@@ -0,0 +1,224 @@
+# Guild Configuration Schema
+# This defines the structure and validation rules for guild configurations
+
+type: object
+required:
+  - guild_id
+  - name
+  - settings
+
+properties:
+  guild_id:
+    type: integer
+    description: "Discord guild (server) ID"
+    minimum: 1
+    
+  name:
+    type: string
+    description: "Human-readable guild name"
+    maxLength: 100
+    
+  owner_id:
+    type: integer
+    description: "Guild owner's Discord user ID"
+    minimum: 1
+    
+  premium:
+    type: boolean
+    description: "Whether this guild has premium features"
+    default: false
+    
+  settings:
+    type: object
+    required:
+      - general
+      - channels
+      - roles
+      - moderation
+      - automod
+      - ai_moderation
+      - verification
+    
+    properties:
+      general:
+        type: object
+        properties:
+          prefix:
+            type: string
+            description: "Command prefix"
+            minLength: 1
+            maxLength: 10
+            default: "!"
+          locale:
+            type: string
+            description: "Language locale"
+            pattern: "^[a-z]{2}$"
+            default: "en"
+            
+      channels:
+        type: object
+        description: "Channel configuration (Discord channel IDs)"
+        properties:
+          log_channel_id:
+            type: [integer, "null"]
+            description: "General event log channel"
+            minimum: 1
+          mod_log_channel_id:
+            type: [integer, "null"]
+            description: "Moderation action log channel"
+            minimum: 1
+          welcome_channel_id:
+            type: [integer, "null"]
+            description: "Welcome message channel"
+            minimum: 1
+            
+      roles:
+        type: object
+        description: "Role configuration (Discord role IDs)"
+        properties:
+          mute_role_id:
+            type: [integer, "null"]
+            description: "Role for timed-out members"
+            minimum: 1
+          verified_role_id:
+            type: [integer, "null"]
+            description: "Role given after verification"
+            minimum: 1
+          mod_role_ids:
+            type: array
+            description: "Moderator roles"
+            items:
+              type: integer
+              minimum: 1
+            default: []
+            
+      moderation:
+        type: object
+        properties:
+          automod_enabled:
+            type: boolean
+            description: "Enable automatic moderation"
+            default: true
+          anti_spam_enabled:
+            type: boolean
+            description: "Enable anti-spam protection"
+            default: true
+          link_filter_enabled:
+            type: boolean
+            description: "Enable link filtering"
+            default: false
+          strike_actions:
+            type: object
+            description: "Actions to take at strike thresholds"
+            patternProperties:
+              "^[0-9]+$":
+                type: object
+                required: [action]
+                properties:
+                  action:
+                    type: string
+                    enum: [warn, timeout, kick, ban]
+                  duration:
+                    type: integer
+                    minimum: 1
+                    description: "Duration in seconds (for timeout/ban)"
+            default:
+              "1": {action: warn}
+              "3": {action: timeout, duration: 3600}
+              "5": {action: kick}
+              "7": {action: ban}
+              
+      automod:
+        type: object
+        description: "Automatic moderation settings"
+        properties:
+          message_rate_limit:
+            type: integer
+            minimum: 1
+            maximum: 50
+            description: "Messages per time window"
+            default: 5
+          message_rate_window:
+            type: integer
+            minimum: 1
+            maximum: 300
+            description: "Time window in seconds"
+            default: 5
+          duplicate_threshold:
+            type: integer
+            minimum: 1
+            maximum: 20
+            description: "Duplicate messages to trigger action"
+            default: 3
+          mention_limit:
+            type: integer
+            minimum: 1
+            maximum: 50
+            description: "Maximum mentions per message"
+            default: 5
+          mention_rate_limit:
+            type: integer
+            minimum: 1
+            maximum: 100
+            description: "Mentions per time window"
+            default: 10
+          mention_rate_window:
+            type: integer
+            minimum: 1
+            maximum: 3600
+            description: "Mention time window in seconds"
+            default: 60
+          scam_allowlist:
+            type: array
+            description: "Domains allowed to bypass scam detection"
+            items:
+              type: string
+              pattern: "^[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+            default: []
+            
+      ai_moderation:
+        type: object
+        description: "AI-powered moderation settings"
+        properties:
+          enabled:
+            type: boolean
+            description: "Enable AI moderation"
+            default: true
+          sensitivity:
+            type: integer
+            minimum: 0
+            maximum: 100
+            description: "AI sensitivity level (higher = stricter)"
+            default: 80
+          confidence_threshold:
+            type: number
+            minimum: 0.0
+            maximum: 1.0
+            description: "Minimum confidence to take action"
+            default: 0.7
+          log_only:
+            type: boolean
+            description: "Only log violations, don't take action"
+            default: false
+          nsfw_detection_enabled:
+            type: boolean
+            description: "Enable NSFW image detection"
+            default: true
+          nsfw_only_filtering:
+            type: boolean
+            description: "Only filter sexual content, allow violence/harassment"
+            default: false
+            
+      verification:
+        type: object
+        description: "Member verification settings"
+        properties:
+          enabled:
+            type: boolean
+            description: "Enable verification for new members"
+            default: false
+          type:
+            type: string
+            enum: [button, captcha, math, emoji]
+            description: "Verification challenge type"
+            default: button

config/schemas/wordlists-schema.yml

@@ -0,0 +1,175 @@
+# Wordlists Configuration Schema
+# Defines structure for banned words and domain whitelists
+
+banned_words:
+  type: object
+  description: "Banned words and patterns configuration"
+  properties:
+    global_patterns:
+      type: array
+      description: "Patterns applied to all guilds (unless overridden)"
+      items:
+        type: object
+        required: [pattern, action]
+        properties:
+          pattern:
+            type: string
+            description: "Word or regex pattern to match"
+            minLength: 1
+            maxLength: 200
+          action:
+            type: string
+            enum: [delete, warn, strike, timeout]
+            description: "Action to take when pattern matches"
+          is_regex:
+            type: boolean
+            description: "Whether pattern is a regular expression"
+            default: false
+          reason:
+            type: string
+            description: "Reason for this rule"
+            maxLength: 500
+          category:
+            type: string
+            description: "Category of banned content"
+            enum: [profanity, hate_speech, spam, scam, harassment, sexual, violence]
+          severity:
+            type: integer
+            minimum: 1
+            maximum: 10
+            description: "Severity level (1-10)"
+            default: 5
+          enabled:
+            type: boolean
+            description: "Whether this rule is active"
+            default: true
+            
+    guild_patterns:
+      type: object
+      description: "Guild-specific pattern overrides"
+      patternProperties:
+        "^[0-9]+$":  # Guild ID
+          type: array
+          items:
+            type: object
+            required: [pattern, action]
+            properties:
+              pattern:
+                type: string
+                minLength: 1
+                maxLength: 200
+              action:
+                type: string
+                enum: [delete, warn, strike, timeout]
+              is_regex:
+                type: boolean
+                default: false
+              reason:
+                type: string
+                maxLength: 500
+              category:
+                type: string
+                enum: [profanity, hate_speech, spam, scam, harassment, sexual, violence]
+              severity:
+                type: integer
+                minimum: 1
+                maximum: 10
+                default: 5
+              enabled:
+                type: boolean
+                default: true
+              override_global:
+                type: boolean
+                description: "Whether this rule overrides global patterns"
+                default: false
+
+external_sources:
+  type: object
+  description: "External wordlist sources configuration"
+  properties:
+    sources:
+      type: array
+      items:
+        type: object
+        required: [name, url, category, action]
+        properties:
+          name:
+            type: string
+            description: "Unique identifier for this source"
+            pattern: "^[a-zA-Z0-9_-]+$"
+          url:
+            type: string
+            description: "URL to fetch wordlist from"
+            format: uri
+          category:
+            type: string
+            enum: [profanity, hate_speech, spam, scam, harassment, sexual, violence]
+          action:
+            type: string
+            enum: [delete, warn, strike, timeout]
+          reason:
+            type: string
+            description: "Default reason for words from this source"
+          enabled:
+            type: boolean
+            default: true
+          update_interval_hours:
+            type: integer
+            minimum: 1
+            maximum: 8760  # 1 year
+            description: "How often to update from source"
+            default: 168   # 1 week
+          applies_to_guilds:
+            type: array
+            description: "Guild IDs to apply this source to (empty = all guilds)"
+            items:
+              type: integer
+              minimum: 1
+            default: []
+
+domain_allowlists:
+  type: object
+  description: "Domain whitelist configuration"
+  properties:
+    global_allowlist:
+      type: array
+      description: "Domains allowed for all guilds"
+      items:
+        type: object
+        required: [domain]
+        properties:
+          domain:
+            type: string
+            description: "Domain name to allow"
+            pattern: "^[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+          reason:
+            type: string
+            description: "Why this domain is allowed"
+          added_by:
+            type: string
+            description: "Who added this domain"
+          added_date:
+            type: string
+            format: date-time
+            description: "When this domain was added"
+            
+    guild_allowlists:
+      type: object
+      description: "Guild-specific domain allowlists"
+      patternProperties:
+        "^[0-9]+$":  # Guild ID
+          type: array
+          items:
+            type: object
+            required: [domain]
+            properties:
+              domain:
+                type: string
+                pattern: "^[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+              reason:
+                type: string
+              added_by:
+                type: string
+              added_date:
+                type: string
+                format: date-time

config/templates/guild-default.yml

@@ -0,0 +1,102 @@
+# Default Guild Configuration Template
+# Copy this file to config/guilds/guild-{GUILD_ID}.yml and customize
+
+# Guild Information
+guild_id: 123456789012345678  # Replace with your Discord server ID
+name: "My Discord Server"     # Replace with your server name
+owner_id: 987654321098765432  # Replace with owner's Discord user ID
+premium: false                # Set to true if you have premium features
+
+settings:
+  # General Settings
+  general:
+    prefix: "!"                # Command prefix (if keeping read-only commands)
+    locale: "en"              # Language code (en, es, fr, de, etc.)
+    
+  # Channel Configuration (Discord Channel IDs)
+  # Set to null to disable, or use actual channel IDs
+  channels:
+    log_channel_id: null           # General event logging
+    mod_log_channel_id: null       # Moderation action logging  
+    welcome_channel_id: null       # New member welcome messages
+    
+  # Role Configuration (Discord Role IDs)
+  roles:
+    mute_role_id: null            # Role for timed-out members
+    verified_role_id: null        # Role given after verification
+    mod_role_ids: []              # List of moderator role IDs
+    
+  # Moderation Settings
+  moderation:
+    automod_enabled: true         # Enable automatic moderation
+    anti_spam_enabled: true       # Enable anti-spam protection
+    link_filter_enabled: false    # Enable suspicious link filtering
+    
+    # Strike System - Actions taken when users reach strike thresholds
+    strike_actions:
+      "1":                        # At 1 strike
+        action: warn
+      "3":                        # At 3 strikes  
+        action: timeout
+        duration: 3600            # 1 hour timeout
+      "5":                        # At 5 strikes
+        action: kick
+      "7":                        # At 7 strikes
+        action: ban
+        
+  # Automatic Moderation Thresholds
+  automod:
+    # Message Rate Limiting
+    message_rate_limit: 5         # Max messages per time window
+    message_rate_window: 5        # Time window in seconds
+    duplicate_threshold: 3        # Duplicate messages to trigger action
+    
+    # Mention Spam Protection  
+    mention_limit: 5              # Max mentions per message
+    mention_rate_limit: 10        # Max mentions per time window
+    mention_rate_window: 60       # Mention time window in seconds
+    
+    # Scam Protection - Domains allowed to bypass scam detection
+    scam_allowlist:
+      - "discord.com"             # Example: Allow Discord links
+      - "github.com"              # Example: Allow GitHub links
+      # Add trusted domains here
+      
+  # AI-Powered Moderation
+  ai_moderation:
+    enabled: true                 # Enable AI content analysis
+    sensitivity: 80               # AI sensitivity (0-100, higher = stricter)
+    confidence_threshold: 0.7     # Minimum confidence to take action (0.0-1.0)
+    log_only: false               # Only log violations (true) or take action (false)
+    nsfw_detection_enabled: true  # Enable NSFW image detection
+    nsfw_only_filtering: false    # Only filter sexual content (true) vs all content (false)
+    
+  # Member Verification System
+  verification:
+    enabled: false                # Enable verification for new members
+    type: "button"                # Verification type: button, captcha, math, emoji
+
+# Configuration Notes:
+# 
+# NSFW-Only Filtering:
+#   false = Block all inappropriate content (sexual, violence, harassment, hate speech)
+#   true  = Only block sexual/nude content, allow violence and harassment
+#
+# AI Sensitivity Guide:
+#   0-30   = Very lenient (only extreme violations)
+#   31-50  = Lenient (clear violations)  
+#   51-70  = Balanced (moderate detection)
+#   71-85  = Strict (catches most issues)
+#   86-100 = Very strict (may have false positives)
+#
+# Verification Types:
+#   button = Simple button click (easiest)
+#   captcha = Text-based captcha entry
+#   math = Solve simple math problem
+#   emoji = Select correct emoji from options
+#
+# Strike Actions:
+#   warn = Send warning message
+#   timeout = Temporarily mute user (requires duration in seconds)
+#   kick = Remove user from server (can rejoin)
+#   ban = Permanently ban user from server

config/wordlists/banned-words.yml

@@ -0,0 +1,95 @@
+# Banned Words Configuration
+# Manage blocked words and patterns for content filtering
+
+# Global patterns applied to all guilds (unless overridden)
+global_patterns:
+  # Basic profanity filter
+  - pattern: "badword1"
+    action: delete
+    is_regex: false
+    reason: "Basic profanity filter"
+    category: profanity
+    severity: 5
+    enabled: true
+    
+  - pattern: "badword2"
+    action: warn
+    is_regex: false
+    reason: "Mild profanity"
+    category: profanity
+    severity: 3
+    enabled: true
+    
+  # Regex example for variations
+  - pattern: "sp[a4]mm*[i1]ng"
+    action: delete
+    is_regex: true
+    reason: "Spam pattern detection"
+    category: spam
+    severity: 7
+    enabled: true
+    
+  # Hate speech prevention
+  - pattern: "hate.*speech.*example"
+    action: timeout
+    is_regex: true
+    reason: "Hate speech filter"
+    category: hate_speech
+    severity: 9
+    enabled: true
+
+# Guild-specific pattern overrides
+# Use your Discord server ID as the key
+guild_patterns:
+  123456789012345678:  # Replace with actual guild ID
+    - pattern: "guild-specific-word"
+      action: warn
+      is_regex: false
+      reason: "Server-specific rule"
+      category: harassment
+      severity: 4
+      enabled: true
+      override_global: false
+      
+    - pattern: "allowed-here"
+      action: delete
+      is_regex: false
+      reason: "Disable global pattern for this guild"
+      category: profanity
+      severity: 1
+      enabled: false        # Disabled = allows the word in this guild
+      override_global: true  # Overrides global patterns
+      
+  # Add more guild IDs as needed
+  # 987654321098765432:
+  #   - pattern: "another-server-rule"
+  #     action: strike
+  #     [...]
+
+# Configuration Notes:
+#
+# Actions Available:
+#   delete  = Delete the message immediately
+#   warn    = Send warning to user and log
+#   strike  = Add strike to user (triggers escalation)
+#   timeout = Temporarily mute user
+#
+# Regex Patterns:
+#   is_regex: true allows advanced pattern matching
+#   Examples:
+#     - "hell+o+" matches "hello", "helllo", "helloooo"
+#     - "[a4]dmin" matches "admin" or "4dmin"
+#     - "spam.*bot" matches "spam bot", "spambot", "spam detection bot"
+#   
+# Categories:
+#   profanity, hate_speech, spam, scam, harassment, sexual, violence
+#
+# Severity (1-10):
+#   1-3 = Mild violations (warnings)
+#   4-6 = Moderate violations (delete message)
+#   7-8 = Serious violations (timeout)
+#   9-10 = Severe violations (kick/ban)
+#
+# Override Global:
+#   false = Use this rule in addition to global patterns
+#   true = This rule replaces global patterns for this guild

config/wordlists/domain-allowlists.yml

@@ -0,0 +1,99 @@
+# Domain Allowlists Configuration
+# Configure domains that bypass scam/phishing detection
+
+# Global allowlist - applies to all guilds
+global_allowlist:
+  - domain: "discord.com"
+    reason: "Official Discord domain"
+    added_by: "system"
+    added_date: "2026-01-24T00:00:00Z"
+    
+  - domain: "github.com"
+    reason: "Popular code repository platform"
+    added_by: "admin"
+    added_date: "2026-01-24T00:00:00Z"
+    
+  - domain: "youtube.com"
+    reason: "Popular video platform"
+    added_by: "admin"
+    added_date: "2026-01-24T00:00:00Z"
+    
+  - domain: "youtu.be"
+    reason: "YouTube short links"
+    added_by: "admin"
+    added_date: "2026-01-24T00:00:00Z"
+    
+  - domain: "imgur.com"
+    reason: "Popular image hosting"
+    added_by: "admin"
+    added_date: "2026-01-24T00:00:00Z"
+    
+  - domain: "reddit.com"
+    reason: "Popular discussion platform"
+    added_by: "admin"
+    added_date: "2026-01-24T00:00:00Z"
+    
+  - domain: "wikipedia.org"
+    reason: "Educational content"
+    added_by: "admin"
+    added_date: "2026-01-24T00:00:00Z"
+
+# Guild-specific allowlists
+# Use your Discord server ID as the key
+guild_allowlists:
+  123456789012345678:  # Replace with actual guild ID
+    - domain: "example-gaming-site.com"
+      reason: "Popular gaming community site"
+      added_by: "guild_admin"
+      added_date: "2026-01-24T00:00:00Z"
+      
+    - domain: "guild-specific-forum.com"
+      reason: "Guild's official forum"
+      added_by: "guild_owner"
+      added_date: "2026-01-24T00:00:00Z"
+      
+  # Add more guild IDs as needed
+  # 987654321098765432:
+  #   - domain: "another-server-site.com"
+  #     reason: "Server-specific trusted site"
+  #     added_by: "admin"
+  #     added_date: "2026-01-24T00:00:00Z"
+
+# Configuration Notes:
+#
+# Domain Format:
+#   - Use base domain only (e.g., "example.com" not "https://www.example.com/path")
+#   - Subdomains are automatically included (allowing "example.com" also allows "www.example.com")
+#   - Do not include protocols (http/https) or paths
+#
+# Why Allowlist Domains:
+#   - Prevent false positives in scam detection
+#   - Allow trusted community sites and resources
+#   - Whitelist official platforms and services
+#   - Support educational and reference materials
+#
+# Security Considerations:
+#   - Only add domains you trust completely
+#   - Regularly review and update the list
+#   - Remove domains that become compromised
+#   - Be cautious with URL shorteners
+#
+# Common Domains to Consider:
+#   - Social platforms: twitter.com, instagram.com, tiktok.com
+#   - Gaming: steam.com, epicgames.com, battle.net, minecraft.net
+#   - Development: gitlab.com, stackoverflow.com, npm.org
+#   - Media: twitch.tv, spotify.com, soundcloud.com
+#   - Education: khan.org, coursera.org, edx.org
+#   - News: bbc.com, reuters.com, apnews.com
+#
+# Guild-Specific vs Global:
+#   - Global allowlist applies to all servers
+#   - Guild-specific allowlists are additional (don't override global)
+#   - Use guild-specific for community-specific trusted sites
+#   - Use global for widely trusted platforms
+#
+# Maintenance:
+#   - Review allowlist monthly for security
+#   - Document reasons for all additions
+#   - Track who added each domain for accountability
+#   - Monitor for changes in domain ownership or compromise

config/wordlists/external-sources.yml

@@ -0,0 +1,74 @@
+# External Wordlist Sources Configuration
+# Configure automatic wordlist updates from external sources
+
+sources:
+  # Default profanity list (LDNOOBW)
+  - name: "ldnoobw_en"
+    url: "https://raw.githubusercontent.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words/master/en"
+    category: profanity
+    action: warn
+    reason: "External profanity list (English)"
+    enabled: true
+    update_interval_hours: 168  # Update weekly
+    applies_to_guilds: []       # Empty = applies to all guilds
+    
+  # Additional language support (uncomment and configure as needed)
+  # - name: "ldnoobw_es"
+  #   url: "https://raw.githubusercontent.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words/master/es"
+  #   category: profanity
+  #   action: warn
+  #   reason: "External profanity list (Spanish)"
+  #   enabled: false
+  #   update_interval_hours: 168
+  #   applies_to_guilds: []
+    
+  # Custom external source example
+  # - name: "custom_hate_speech"
+  #   url: "https://example.com/hate-speech-list.txt"
+  #   category: hate_speech
+  #   action: delete
+  #   reason: "Custom hate speech prevention"
+  #   enabled: false
+  #   update_interval_hours: 24    # Update daily
+  #   applies_to_guilds: [123456789012345678]  # Only for specific guild
+    
+  # Scam/phishing domains (if available)
+  # - name: "phishing_domains"
+  #   url: "https://example.com/phishing-domains.txt"
+  #   category: scam
+  #   action: delete
+  #   reason: "Known phishing domains"
+  #   enabled: false
+  #   update_interval_hours: 4     # Update every 4 hours
+  #   applies_to_guilds: []
+
+# Configuration Notes:
+#
+# Update Intervals:
+#   1-6 hours   = High-risk content (scams, phishing)
+#   12-24 hours = Moderate risk content
+#   168 hours   = Weekly updates (default for profanity)
+#   720 hours   = Monthly updates (stable lists)
+#
+# Applies to Guilds:
+#   []              = Apply to all guilds
+#   [123, 456]      = Only apply to specific guild IDs
+#   ["all_premium"] = Apply only to premium guilds (if implemented)
+#
+# Categories determine how content is classified and what AI moderation
+# settings apply to the detected content.
+#
+# Actions determine the default action taken when words from this source
+# are detected. Guild-specific overrides can modify this behavior.
+#
+# URL Requirements:
+#   - Must be publicly accessible
+#   - Should return plain text with one word/pattern per line
+#   - HTTPS URLs preferred for security
+#   - Consider rate limiting and source reliability
+#
+# Security Notes:
+#   - External sources are validated before applying
+#   - Malformed or suspicious content is logged but not applied
+#   - Sources that fail repeatedly are automatically disabled
+#   - All updates are logged for audit purposes