diff --git a/docs/consultations/gemini-arbiter-discord-roles-round-1-2026-04-13.md b/docs/consultations/gemini-arbiter-discord-roles-round-1-2026-04-13.md new file mode 100644 index 0000000..cf7d6a5 --- /dev/null +++ b/docs/consultations/gemini-arbiter-discord-roles-round-1-2026-04-13.md @@ -0,0 +1,88 @@ +# Gemini Consultation: Arbiter Discord Role Automation — Round 1 + +**Date:** April 13, 2026 +**From:** Michael (The Wizard) + Claude (Chronicler #86) +**To:** Gemini (Architectural Partner) +**Re:** Should Arbiter replace Carlbot for role assignment, and how should it manage the get-roles message dynamically? + +--- + +## Hey Gemini! 👋 + +Hope you're doing well! We're in the home stretch before launch (April 15) and we're thinking ahead to a quality-of-life improvement that's been bugging us. We currently use Carlbot for welcome messages and reaction-based role assignment, but every time we create or delete a Minecraft server we have to manually update Carlbot's config. We want to eliminate those manual steps entirely — and we think Arbiter is the right home for this. We'd love your architectural take before Code starts building. + +--- + +## The Situation + +**Current stack:** +- **Arbiter 3.0** — Node.js/Express on Command Center (63.143.34.217), handles Stripe webhooks, Discord role management, Trinity Console admin dashboard. Already has the Discord bot token and full API access. +- **Carlbot** — External bot currently handling: welcome messages on member join, reaction roles in a `#get-roles` channel, and Wanderer role assignment on join. +- **Pterodactyl panel** — Minecraft servers managed via `/createserver` and `/delserver` Pterodactyl commands that Arbiter responds to. + +**The pain points:** + +When `/createserver` runs, the admin must manually: +1. Add a new emoji reaction to the `#get-roles` message in Discord +2. Configure Carlbot to map that emoji → new server role + +When `/delserver` runs, the admin must manually: +1. Remove the emoji reaction from `#get-roles` +2. Remove the role mapping from Carlbot + +This is error-prone, easy to forget, and completely automatable. + +**Current `#get-roles` setup:** +- Single message with emoji reactions +- Each emoji maps to a Minecraft server role (e.g., 🌾 = Farm Crossing 6) +- Members react to get the role, unreact to remove it +- Carlbot handles the reaction → role assignment logic + +--- + +## What We're Trying to Do + +Replace Carlbot's role assignment function with **native Arbiter handling**, using **button-based role selection** instead of reaction roles. The goals are: + +1. **Fully automate** the get-roles message — when Arbiter creates or deletes a server, the button message updates automatically with no manual steps +2. **Better UX** — buttons give members visual confirmation of selection (active/inactive state or ephemeral confirmation), which reaction roles don't provide +3. **One less external dependency** — keep community experience inside FFG's own stack +4. **Keep welcome messages** in Arbiter too while we're at it + +The `#get-roles` message would be a persistent embed managed by Arbiter, with one button per active Minecraft server. Clicking a button toggles the corresponding Discord role on/off for that member. + +--- + +## Specific Questions + +1. **Architecture for the button message:** What's the cleanest pattern for Arbiter to manage a single persistent "get-roles" message that updates dynamically as servers are added/removed? Should we store the message ID in the database and edit it in place, or delete/repost? What are the tradeoffs? + +2. **Button interaction handling:** Discord button interactions require a response within 3 seconds or they fail. Arbiter is an Express app, not a traditional Discord bot with a gateway connection. We use the Discord REST API. Is this a problem for handling button interactions, and if so, what's the recommended approach? (We're aware of the interactions endpoint / public key verification flow.) + +3. **Button UX for role toggling:** What's the best way to visually indicate to a member which roles they already have? Options we're considering: (a) re-render the message with updated button styles when someone interacts, (b) ephemeral reply only, (c) both. What do you recommend for this use case? + +4. **Welcome messages:** For the welcome message on member join, Arbiter already listens for Discord gateway events via its bot token... or does it? Actually — does a REST-only bot receive gateway events like `GUILD_MEMBER_ADD`? If not, what's the right approach for welcome messages in an Express/REST architecture? + +5. **Scope and risk for launch:** We're 2 days from soft launch (April 15). Is this the right time to migrate off Carlbot, or should we implement Arbiter's role system in parallel first, validate it, then cut over? What's the minimum viable first step? + +--- + +## Context That Might Help + +- Arbiter is Node.js/Express, deployed as a systemd service, no build pipeline +- We already use `discord.js` or raw REST calls in Arbiter for role assignment (Stripe webhook → Discord role grant on subscription) +- The `#get-roles` channel ID is `1260574715546701936` (actually that's the guild — we have the correct channel ID available) +- Servers are created/deleted via Pterodactyl webhooks that Arbiter already receives +- We have a `servers` table concept (via Pterodactyl) — server name, UUID, status +- Code (Claude Code) will be implementing this — he's been deep in ModpackChecker and would welcome a different kind of feature +- Holly asked a great question: "How do players know what's selected?" — which is part of why we want buttons over reactions + +--- + +Thanks Gemini! As always, your perspective before we build saves us a lot of pain. 🔥❄️ + +— Michael + Claude (Chronicler #86) + +--- + +*[Gemini's response will be added here after consultation]*