docs: update

Author: wescopeland

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -21,14 +21,12 @@ bun run lint            # Run oxlint
 bun run lint:fix        # Auto-fix linting issues (oxlint)
 bun run test            # Run all tests (vitest)
 bun run test:watch      # Run tests in watch mode (vitest)
-bun run verify          # Run format check, lint, type checking, and tests
+bun run verify          # Format, lint-fix, type check, and test locally
+bun run ci              # CI-safe checks without writing files
 
 # Deployment
 bun run deploy-commands # Deploy slash commands to Discord (required after adding/modifying slash commands)
 bun run start           # Production mode
-
-# Database management
-bun run db:studio       # Open Drizzle Studio GUI
 ```
 
 ## Architecture & Key Patterns
@@ -40,7 +38,7 @@ The bot supports both legacy prefix commands and modern slash commands during th
 1. **Legacy Commands** (`src/commands/*.command.ts`)
    - Use the `Command` interface
    - Accessed via prefix (default: `!`)
-   - Show migration notices encouraging slash command use
+   - May show migration notices when linked to slash command replacements
    - Example: `!gan 14402`
 
 2. **Slash Commands** (`src/slash-commands/*.command.ts`)
@@ -51,15 +49,16 @@ The bot supports both legacy prefix commands and modern slash commands during th
 
 ### Migration System
 
-When users use legacy commands that have slash equivalents:
+When users use legacy commands that are linked to slash equivalents via `legacyName`:
 
 - A temporary migration notice appears (15 seconds)
 - The legacy command still executes
-- Configured via `legacyName` property in slash commands
+- `!poll` currently keeps running without a migration notice
+- The mapping is configured via the `legacyName` property in slash commands
 
 ### Database Architecture
 
-- **Drizzle ORM** with SQLite (`bun:sqlite`)
+- **Drizzle ORM** with SQLite through the libSQL client
 - Schema defined in `src/database/schema.ts`
 - Services pattern for database operations (`src/services/*.service.ts`)
 - Tables: `teams`, `team_members`, `polls`, `poll_votes`, `uwc_polls`, `uwc_poll_results`
@@ -77,23 +76,32 @@ When users use legacy commands that have slash equivalents:
 - **UwcPollService**: Tracks UWC polls, stores results, enables searching by achievement/game
 - **UwcHistoryService**: Retrieves and formats previous UWC poll history for auto-detection
 - **AutoPublishService**: Automatically publishes messages in configured announcement channels
+- **GameInfoService**, **TemplateService**, and **YouTubeService**: Power GAN command data fetching and formatting
+- **AchievementUnlocksService** and **ConnectApiService**: Support events and memory parsing features
+- **GithubReleaseService**: Fetches release information for `/status`
 
 ### Environment Variables
 
-Required in `.env`:
+Required at startup:
 
 - `DISCORD_TOKEN`: Bot token (required)
 - `DISCORD_APPLICATION_ID`: Bot application ID (required)
 - `RA_WEB_API_KEY`: RetroAchievements Web API key (required)
+
+Feature-specific and optional configuration:
+
 - `LEGACY_COMMAND_PREFIX`: Prefix for legacy commands (default: `!`)
-- `RA_CONNECT_API_KEY`: RetroAchievements Connect API key (future use)
+- `RA_CONNECT_API_KEY`: RetroAchievements Connect API key required for `!mem` achievement ID/URL lookups and code notes
+- `RA_CONNECT_API_USER`: RetroAchievements Connect API username (default: `RABot`)
 - `YOUTUBE_API_KEY`: For longplay searches in gan commands (optional, but recommended)
-- `MAIN_GUILD_ID`: Discord guild ID for the main RetroAchievements server (optional, but recommended)
-- `WORKSHOP_GUILD_ID`: Discord guild ID for the RetroAchievements Workshop server (optional, but recommended)
+- `MAIN_GUILD_ID`: Discord guild ID for the main RetroAchievements server (optional, but recommended for production guild authorization)
+- `WORKSHOP_GUILD_ID`: Discord guild ID for the RetroAchievements Workshop server (required for Workshop-only features)
 - `CHEAT_INVESTIGATION_CATEGORY_ID`: Category ID for RACheats team restrictions
+- `GAMBLER_ROLE_ID`: Discord role ID managed by `/events gambler` (required for Gambler role commands)
 - `UWC_VOTING_TAG_ID`: Forum tag ID for active UWC polls (optional)
 - `UWC_VOTE_CONCLUDED_TAG_ID`: Forum tag ID for completed UWC polls (optional)
 - `UWC_FORUM_CHANNEL_ID`: Forum channel ID for UWC auto-detection feature (optional)
+- `DEV_CHANNELS`: Comma-separated channel IDs where `!mem` may show code notes (optional)
 - `AUTO_PUBLISH_CHANNEL_IDS`: Comma-separated list of announcement channel IDs to auto-publish from (optional)
 - `NODE_ENV`: Set to "production" in production (default: "development")
 - `LOG_LEVEL`: Logging level - trace, debug, info, warn, error, fatal (default: "debug" in dev, "info" in prod)
@@ -114,7 +122,7 @@ The bot automatically provides context when new UWC (Unwelcome Concept) reports
 - Detects threads matching pattern: `12345: Achievement Title (Game Name)`
 - Queries database for previous UWC polls for the same achievement ID
 - Posts an automated message with links to up to 5 previous discussions
-- Shows poll dates, outcomes (Approved/Denied/Active/No Action), and vote results
+- Shows poll dates, active status when relevant, and the top vote result when available
 - Uses efficient database queries instead of Discord API calls for performance
 
 ### Auto-Publishing Feature
@@ -175,7 +183,7 @@ async execute(interaction, _client) {
 
 ## Logging System
 
-The bot uses Pino for structured logging with the following features:
+The bot uses a small custom structured JSON logger with the following features:
 
 ### Log Levels
 
@@ -223,10 +231,10 @@ The bot uses Pino for structured logging with the following features:
 - Runs under a process supervisor on the production server
 - No manual PM2 configuration needed
 
-### Database Performance
+### Database
 
-- SQLite WAL mode is enabled by default for better concurrent access
-- WAL mode allows concurrent reads during writes, ideal for Discord bot usage patterns
+- The database is a local SQLite file (`rabot.db`) accessed through Drizzle's libSQL adapter
+- Migrations live in `drizzle/` and are applied by `bun run db:migrate`
 
 ### Shutdown Handling
 
@@ -241,7 +249,7 @@ Tests use [Vitest](https://vitest.dev/) as the test runner (configured in `vites
 ## Common Gotchas
 
 - Always use Bun commands (`bun run`, `bun install`) not npm/yarn/pnpm
-- Deploy slash commands after changes (`bun deploy-commands`)
+- Deploy slash commands after changes (`bun run deploy-commands`)
 - Check channel type before accessing properties like `topic` or `parentId`
 - Use proper null checks for Discord.js properties
 - Remember to handle both team IDs and names in TeamService methods

CONTRIBUTING.md

@@ -6,17 +6,18 @@ Thank you for your interest in contributing to RABot! This document provides gui
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) 1.2.18 or higher
+- [Bun](https://bun.sh) 1.3.10 or higher
 - A Discord application for testing (create one at [Discord Developer Portal](https://discord.com/developers/applications))
+- A RetroAchievements Web API key for local bot startup
 - Basic knowledge of TypeScript and Discord.js
 
 ### Setting Up Your Development Environment
 
 1. **Fork and clone the repository**
 
    ```bash
-   git clone https://github.com/YOUR-USERNAME/RABot.git
-   cd RABot
+   git clone https://github.com/YOUR-USERNAME/RABot-Next.git
+   cd RABot-Next
    ```
 
 2. **Install dependencies**
@@ -36,20 +37,20 @@ Thank you for your interest in contributing to RABot! This document provides gui
 4. **Initialize the database**
 
    ```bash
-   bun db:generate
-   bun db:migrate
-   bun db:seed  # Optional: adds default teams
+   bun run db:generate
+   bun run db:migrate
+   bun run db:seed  # Optional: adds default teams
    ```
 
-5. **Deploy slash commands to your test server**
+5. **Deploy global slash commands**
 
    ```bash
-   bun deploy-commands
+   bun run deploy-commands
    ```
 
 6. **Run the bot in development mode**
    ```bash
-   bun dev
+   bun run dev
    ```
 
 ## Development Workflow
@@ -76,21 +77,24 @@ git checkout -b fix/issue-description
 Before committing, ensure your code passes all checks:
 
 ```bash
-bun run verify  # Runs lint, type checking, and tests
+bun run verify  # Formats, lint-fixes, type checks, and tests
 ```
 
+Use `bun run ci` when you want the non-mutating CI check sequence.
+
 Individual checks:
 
 ```bash
-bun lint        # Check code style
-bun lint:fix    # Auto-fix style issues
-bun tsc         # TypeScript type checking (via tsgo)
-bun run test    # Run tests (via vitest)
+bun run format:check  # Check formatting without writing
+bun run lint          # Check code style
+bun run lint:fix      # Auto-fix lint issues
+bun run tsc           # TypeScript type checking (via tsgo)
+bun run test          # Run tests (via vitest)
 ```
 
 ### 4. Commit Your Changes
 
-- Use **conventional commits** format:
+- Use **commitizen-style conventional commits** format:
   - `feat:` for new features
   - `fix:` for bug fixes
   - `docs:` for documentation changes
@@ -110,7 +114,7 @@ git commit -m "docs: update setup instructions for Bun 1.3"
 
 1. Push your branch to your fork
 2. Open a pull request against the `main` branch
-3. Fill out the pull request template with:
+3. Include in the pull request description:
    - Clear description of changes
    - Testing instructions
    - Any breaking changes
@@ -130,6 +134,7 @@ git commit -m "docs: update setup instructions for Bun 1.3"
 - **Commands** go in `src/commands/` (legacy) or `src/slash-commands/` (preferred).
 - **Business logic** belongs in `src/services/`.
 - **Shared utilities** go in `src/utils/`.
+- **Shared test helpers** go in `src/test/`.
 - **Database operations** use the service layer pattern.
 
 ### Command Development
@@ -145,6 +150,7 @@ When creating new commands:
 Example slash command structure:
 
 ```typescript
+import { SlashCommandBuilder } from "discord.js";
 import type { SlashCommand } from "../models";
 
 export default {

README.md

@@ -28,8 +28,8 @@ RABot utilizes:
 
 ## Requirements
 
-- [Bun](https://bun.sh) 1.3.6+
-- A Discord bot token
+- [Bun](https://bun.sh) 1.3.10+
+- A Discord application ID, bot token, and RetroAchievements Web API key
 
 ## Installation
 
@@ -55,12 +55,17 @@ Then edit `.env` with your configuration:
 - `DISCORD_APPLICATION_ID` - Your bot's application ID from Discord Developer Portal
 - `LEGACY_COMMAND_PREFIX` - Command prefix for legacy commands (default: `!`)
 - `RA_WEB_API_KEY` - Your RetroAchievements Web API key
+- `RA_CONNECT_API_KEY` - RetroAchievements Connect API key required for `!mem` achievement ID/URL lookups and code notes
+- `RA_CONNECT_API_USER` - RetroAchievements Connect API username (default: `RABot`)
 - `YOUTUBE_API_KEY` - Your YouTube Data API v3 key (optional, for `/gan` longplay searches)
-- `MAIN_GUILD_ID` - Discord guild ID for the main RetroAchievements server
-- `WORKSHOP_GUILD_ID` - Discord guild ID for the RetroAchievements Workshop server
+- `MAIN_GUILD_ID` - Discord guild ID for the main RetroAchievements server (optional, but recommended for production guild authorization)
+- `WORKSHOP_GUILD_ID` - Discord guild ID for the RetroAchievements Workshop server (required for Workshop-only features)
+- `GAMBLER_ROLE_ID` - Discord role ID managed by `/events gambler` (required for Gambler role commands)
+- `CHEAT_INVESTIGATION_CATEGORY_ID` - Category ID required for RACheats `/pingteam ping` restrictions
 - `UWC_VOTING_TAG_ID` - Forum tag ID for active UWC polls (optional)
 - `UWC_VOTE_CONCLUDED_TAG_ID` - Forum tag ID for completed UWC polls (optional)
 - `UWC_FORUM_CHANNEL_ID` - Forum channel ID for UWC auto-detection (optional)
+- `DEV_CHANNELS` - Comma-separated channel IDs where `!mem` may show code notes (optional)
 - `AUTO_PUBLISH_CHANNEL_IDS` - Comma-separated list of announcement channel IDs to auto-publish from (optional)
 - `NODE_ENV` - Environment mode: `development` or `production` (default: `development`)
 - `LOG_LEVEL` - Logging level: `trace`, `debug`, `info`, `warn`, `error`, `fatal` (default: `debug` in dev, `info` in prod)
@@ -70,17 +75,17 @@ Then edit `.env` with your configuration:
 Initialize the database:
 
 ```bash
-bun db:generate  # Generate migration files
-bun db:migrate   # Apply migrations
-bun db:seed      # Seed default teams (optional)
+bun run db:generate  # Generate migration files
+bun run db:migrate   # Apply migrations
+bun run db:seed      # Seed default teams (optional)
 ```
 
 ## Deploying Slash Commands
 
-After adding your bot to a server, deploy the slash commands:
+Deploy the application's global slash commands:
 
 ```bash
-bun deploy-commands
+bun run deploy-commands
 ```
 
 This needs to be run:
@@ -94,38 +99,40 @@ This needs to be run:
 ### Development
 
 ```bash
-bun dev  # Runs with auto-restart on file changes
+bun run dev  # Runs with auto-restart on file changes
 ```
 
 ### Production
 
 ```bash
-bun start  # Standard run
+bun run start  # Standard run
 ```
 
 For production deployments, the bot is automatically deployed via Forge when changes are merged to the main branch. The bot runs under a process supervisor on the production server.
 
 ## Available Scripts
 
-- `bun dev` - Run in development mode with hot reload
-- `bun start` - Run in production mode
-- `bun deploy-commands` - Deploy slash commands to Discord
-- `bun db:generate` - Generate database migrations
-- `bun db:migrate` - Apply database migrations
+- `bun run dev` - Run in development mode with hot reload
+- `bun run start` - Run in production mode
+- `bun run deploy-commands` - Deploy slash commands to Discord
+- `bun run db:generate` - Generate database migrations
+- `bun run db:migrate` - Apply database migrations
+- `bun run db:seed` - Seed default teams
 - `bun run format` - Format code with oxfmt
 - `bun run format:check` - Check formatting without writing
-- `bun lint` - Run oxlint
-- `bun lint:fix` - Run oxlint with auto-fix
-- `bun tsc` - Run TypeScript type checking (via tsgo)
+- `bun run lint` - Run oxlint
+- `bun run lint:fix` - Run oxlint with auto-fix
+- `bun run tsc` - Run TypeScript type checking (via tsgo)
 - `bun run test` - Run all tests
 - `bun run test:watch` - Run tests in watch mode
-- `bun verify` - Run format check, lint, type checking, and tests
+- `bun run verify` - Format, lint-fix, type check, and test locally
+- `bun run ci` - Run CI-safe format check, lint, type checking, and tests
 
 ## Commands
 
 ### 🆕 Migration Notice
 
-RABot is transitioning to slash commands! When you use a legacy prefix command (e.g., `!gan`), you'll see a migration notice encouraging you to use the modern slash command version (e.g., `/gan`). The legacy command will still work during the transition period.
+RABot is transitioning to slash commands. When you use a linked legacy prefix command (for example, `!gan`), you'll see a migration notice encouraging you to use the modern slash command version (for example, `/gan`). The legacy command will still work during the transition period.
 
 ### Slash Commands (Recommended)
 
@@ -138,20 +145,24 @@ RABot is transitioning to slash commands! When you use a legacy prefix command (
 - `/gan2 <game-id>` - Generate pretty achievement news template with colors
 - `/pingteam` - Team management system (Workshop server only)
   - `/pingteam ping <team>` - Ping all members of a team
-  - `/pingteam add <team> <user>` - Add user to team (admin only)
-  - `/pingteam remove <team> <user>` - Remove user from team (admin only)
-  - `/pingteam create <name>` - Create a new team (admin only)
-- `/uwc` - Create an Unwelcome Concept poll (Workshop server only, auto-manages forum tags)
+  - `/pingteam add <team> <user>` - Add user to team
+  - `/pingteam remove <team> <user>` - Remove user from team
+  - `/pingteam create <name>` - Create a new team
+- `/uwc` - Create an Unwelcome Concept poll (Workshop server only, requires UWC role or admin, auto-manages forum tags)
   - **Auto-detection**: When a new UWC thread is created in the configured forum channel with format `12345: Achievement Title (Game Name)`, the bot automatically posts links to previous discussions for that achievement
+- `/events gambler` - Manage the Gambler role (server only)
+  - `/events gambler reset` - Remove the Gambler role from all users
+  - `/events gambler award <user>` - Manually award the Gambler role
+  - `/events gambler award-all <ach1> <ach2> <ach3> [ach4]` - Award the role to users who unlocked at least 3 listed achievements
 - `/dadjoke` - Get a random dad joke
 - `/frames <input>` - Convert between time and frames at different frame rates
 
-### Legacy Prefix Commands (Being Migrated)
+### Legacy Prefix Commands
 
 The bot still supports the following legacy prefix commands (all prefixed with `!` by default):
 
 - `!topic` - Display the current channel topic
-- `!rule [number]` - Display server rules
+- `!rules [number|coc]` - Display server rules (`!rule`, `!rule2`, and `!rulecoc` aliases are also supported)
 - `!contact` - Show contact information for various RA teams
 - `!poll` - Create a simple poll
 - `!tpoll` - Create a timed poll
@@ -171,6 +182,7 @@ src/
 ├── handlers/        # Message and event handlers
 ├── models/          # TypeScript interfaces and types
 ├── services/        # Business logic services
+├── test/            # Shared test database and mocks
 └── utils/           # Utility functions and logging
 ```