Feature/improvments

.env.example

@@ -5,109 +5,221 @@
 # Copy this file to `.env` and fill in real values.
 # NEVER commit `.env` with secrets.
 #
+# Quick setup:
+#   cp .env.example .env
+#   # Edit .env and add your bot token, app ID, and guild ID
+#   npm run register
+#   npm start
+#
 # ============================================================
-# Discord (required)
+# Discord (REQUIRED)
 # ============================================================
 
+# Your Discord bot token from the Developer Portal
+# Get it from: https://discord.com/developers/applications
+# Location: Your App → Bot → Token
+#
+# IMPORTANT: Keep this secret! Never commit it to git.
 DISCORD_TOKEN=
+
+# Your Discord application ID (also called Client ID)
+# Get it from: https://discord.com/developers/applications
+# Location: Your App → General Information → Application ID
+#
+# Used for: Slash command registration
 DISCORD_APP_ID=
+
+# Your development server (guild) ID
+# Get it by: Right-click your server → Copy ID
+# (Requires Developer Mode enabled in Discord settings)
+#
+# Purpose:
+# - If set: Commands register to this guild (instant, recommended for dev)
+# - If unset: Commands register globally (takes ~1 hour to appear)
 DISCORD_GUILD_ID=
 
 # ============================================================
-# Discord Role Automation (optional)
+# Discord Welcome & Onboarding (OPTIONAL)
+# ============================================================
+
+# Channel ID where welcome messages should be sent
+# Get it by: Right-click the channel → Copy ID
+#
+# If unset, welcome messages are disabled.
+DISCORD_WELCOME_CHANNEL_ID=
+
+# ============================================================
+# Discord Role Automation (OPTIONAL)
 # ============================================================
 
 # Auto-assign role ID for new members when they join the server.
 #
 # If set, the bot will attempt to assign this role on guildMemberAdd.
 # If unset, auto-role assignment is skipped.
 #
-# Notes:
+# Requirements:
 # - Must be a numeric role ID (not a role name)
 # - Bot requires "Manage Roles" permission
 # - Bot's role must be ABOVE this role in the role hierarchy
+# - "Server Members Intent" must be enabled in Developer Portal
+#
+# Get it by: Server Settings → Roles → Right-click role → Copy ID
 DISCORD_AUTO_ROLE_ID=
 
 # ============================================================
-# Summaries
+# Conversation Summaries (OPTIONAL)
 # ============================================================
 
-# Summary execution mode:
-# - local  → heuristic / non-LLM summarization
-# - openai → LLM-powered summaries
+# Summary execution mode determines how /summary command works:
+#
+# Options:
+# - local  → Fast heuristic summaries (no API needed, always available)
+# - llm    → High-quality AI summaries using OpenAI (requires API key)
+#
+# Default: local
 SUMMARY_MODE=local
 
-# Required only if SUMMARY_MODE=openai
+# OpenAI API key for LLM-powered summaries
+# Get it from: https://platform.openai.com/api-keys
+#
+# Only required if SUMMARY_MODE=llm
+# Cost: ~$0.01-0.05 per summary (depends on message count)
+#
+# If unset and SUMMARY_MODE=llm, bot falls back to local summaries
 OPENAI_API_KEY=
 
 # ============================================================
-# Weather (WeatherAPI.com)
+# Weather (OPTIONAL)
 # ============================================================
 
-# API key from https://www.weatherapi.com/
+# API key from WeatherAPI.com
+# Get it from: https://www.weatherapi.com/signup.aspx
+# Free tier: 1,000,000 calls/month
 #
 # Used for:
-# - Current weather
+# - /fun weather   → Current weather conditions
+# - /fun weather7  → 7-day forecast
+#
+# Features:
+# - Current weather with feels-like temperature
 # - Multi-day forecasts
 # - Sunrise / sunset times
-# - Local timezone resolution
+# - Automatic timezone resolution
 #
-# Required for /fun weather and /fun weather7
+# If unset, weather commands return a friendly error message
 WEATHERAPI_KEY=
 
 # ============================================================
-# GitHub Integration
+# GitHub Integration (OPTIONAL)
 # ============================================================
 
-# Fine-grained PAT recommended.
+# Personal Access Token (PAT) for GitHub API access
+# Create one: https://github.com/settings/tokens
+#
+# Recommended: Fine-grained token with specific repository access
 # Minimum repository permissions:
 #   - Issues: Read
 #   - Pull requests: Read
+#   - Contents: Read (optional, for file lookups)
+#
+# Classic token scopes (if using classic PAT):
+#   - repo (or public_repo for public repos only)
 #
 # NOTE:
-# For org-owned repositories, this token may require approval by an org admin.
+# For organization-owned repositories, this token may require
+# approval by an organization admin before it works.
 GITHUB_TOKEN=
 
+# GitHub repository owner (organization or username)
+# Example: octocat
 GITHUB_OWNER=
+
+# GitHub repository name (without owner prefix)
+# Example: hello-world
 GITHUB_REPO=
 
 # ============================================================
-# GitHub Announcement Channels (optional)
+# GitHub Announcement Channels (OPTIONAL)
 # ============================================================
 
-# Legacy (fallback) channel:
-# If set, it will be used as the default for GitHub announcements
-# unless a more specific channel is provided below.
+# These channels receive automated GitHub notifications.
+# All are optional. If unset, that type of announcement is disabled.
+#
+# Get channel IDs by: Right-click channel → Copy ID
+
+# Legacy fallback channel for GitHub announcements
+# If set, it will be used as the default for any announcement type
+# that doesn't have its own specific channel configured below.
 GITHUB_ANNOUNCE_CHANNEL_ID=
 
-# PR announcements channel (preferred):
-# Used for:
-# - New PR creation
-# - PR update announcements
+# Channel for pull request announcements
+# Receives:
+# - New PR created
+# - PR updated (title, description)
+# - PR status changes
 #
-# If unset, falls back to GITHUB_ANNOUNCE_CHANNEL_ID.
+# If unset, falls back to GITHUB_ANNOUNCE_CHANNEL_ID
 GITHUB_PR_ANNOUNCE_CHANNEL_ID=
 
-# Assignee + closure activity channel:
-# Used for:
-# - Assignee added / removed
-# - Self-assignment / unassignment
-# - Issue / PR closed events
+# Channel for assignee and closure activity
+# Receives:
+# - Assignee added to issue/PR
+# - Assignee removed from issue/PR
+# - Self-assignment notifications
+# - Issue closed
+# - PR closed/merged
 #
-# If unset, falls back to GITHUB_ANNOUNCE_CHANNEL_ID.
-# If neither is set, assignee polling is disabled.
+# If unset, falls back to GITHUB_ANNOUNCE_CHANNEL_ID
+# If neither is set, assignee polling is disabled
 GITHUB_ASSIGNEE_ANNOUNCE_CHANNEL_ID=
 
 # ============================================================
-# GitHub Polling Interval
+# GitHub Polling Settings (OPTIONAL)
 # ============================================================
 
-# Interval in milliseconds (default: 60 seconds)
+# How often to check GitHub for updates (in milliseconds)
+#
+# Default: 60000 (60 seconds, recommended)
+# Minimum: 30000 (30 seconds, avoid going lower to prevent rate limits)
+# Maximum: 300000 (5 minutes, for low-traffic repos)
+#
+# Note: GitHub API has rate limits:
+# - Authenticated: 5,000 requests/hour
+# - Unauthenticated: 60 requests/hour
 GITHUB_POLL_INTERVAL_MS=60000
 
 # ============================================================
-# Logging
+# Logging (OPTIONAL)
 # ============================================================
 
+# Log level determines what gets logged
+#
+# Options (from most to least verbose):
+# - trace  → Everything (very noisy, debug only)
+# - debug  → Detailed debugging information
+# - info   → General informational messages (recommended)
+# - warn   → Warnings and recoverable errors
+# - error  → Errors only
+# - fatal  → Critical failures only
+#
+# Default: info
 LOG_LEVEL=info
-LOG_PRETTY=true
+
+# Pretty-print logs for human readability
+#
+# Options:
+# - true   → Colorized, formatted logs (good for local development)
+# - false  → JSON logs (good for production/log aggregation)
+#
+# Default: true
+LOG_PRETTY=true
+
+# ============================================================
+# Advanced: Database (OPTIONAL)
+# ============================================================
+
+# Path to SQLite database file
+# Only relevant if using database features (currently not implemented)
+#
+# Default: data/omegabot.db
+# DATABASE_PATH=data/omegabot.db

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [2.0.0] - 2026-01-17
+
+### Changed
+
+- **BREAKING**: Upgraded to Discord.js v14
+  - Updated all interaction handlers to use v14 API
+  - Fixed type narrowing issues with guild checks
+  - Updated permission system for v14 compatibility
+  - Enhanced TypeScript type safety
+
+### Fixed
+
+- Fixed TypeScript compilation errors with type narrowing
+- Fixed FAQ remove command interaction handling
+- Fixed permission middleware type guards
+- Resolved avatar resolution to use maximum 4096px
+- Fixed safeReply type compatibility issues
+
+### Technical
+
+- Updated to Discord.js v14.16.3
+- Improved TypeScript strict mode compliance
+- Enhanced error handling in FAQ subcommands
+- Better type safety across permission checks
+
+---
+
 ## Unreleased
 
 ### Added