opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/discord-bot-architect/references/detailed-guide.md

@@ -0,0 +1,1465 @@
+# Discord Bot Architect - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Principles
+
+- Slash commands over message parsing (Message Content Intent deprecated)
+- Acknowledge interactions within 3 seconds, always
+- Request only required intents (minimize privileged intents)
+- Handle rate limits gracefully with exponential backoff
+- Plan for sharding from the start (required at 2500+ guilds)
+- Use components (buttons, selects, modals) for rich UX
+- Test with guild commands first, deploy global when ready
+
+
+## Patterns
+
+### Discord.js v14 Foundation
+
+Modern Discord bot setup with Discord.js v14 and slash commands
+
+**When to use**: Building Discord bots with JavaScript/TypeScript,Need full gateway connection with events,Building bots with complex interactions
+
+```javascript
+// src/index.js
+const { Client, Collection, GatewayIntentBits, Events } = require('discord.js');
+const fs = require('node:fs');
+const path = require('node:path');
+require('dotenv').config();
+
+// Create client with minimal required intents
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    // Add only what you need:
+    // GatewayIntentBits.GuildMessages,
+    // GatewayIntentBits.MessageContent,  // PRIVILEGED - avoid if possible
+  ]
+});
+
+// Load commands
+client.commands = new Collection();
+const commandsPath = path.join(__dirname, 'commands');
+const commandFiles = fs.readdirSync(commandsPath).filter(f => f.endsWith('.js'));
+
+for (const file of commandFiles) {
+  const filePath = path.join(commandsPath, file);
+  const command = require(filePath);
+  if ('data' in command && 'execute' in command) {
+    client.commands.set(command.data.name, command);
+  }
+}
+
+// Load events
+const eventsPath = path.join(__dirname, 'events');
+const eventFiles = fs.readdirSync(eventsPath).filter(f => f.endsWith('.js'));
+
+for (const file of eventFiles) {
+  const filePath = path.join(eventsPath, file);
+  const event = require(filePath);
+  if (event.once) {
+    client.once(event.name, (...args) => event.execute(...args));
+  } else {
+    client.on(event.name, (...args) => event.execute(...args));
+  }
+}
+
+client.login(process.env.DISCORD_TOKEN);
+```
+
+```javascript
+// src/commands/ping.js
+const { SlashCommandBuilder } = require('discord.js');
+
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName('ping')
+    .setDescription('Replies with Pong!'),
+
+  async execute(interaction) {
+    const sent = await interaction.reply({
+      content: 'Pinging...',
+      fetchReply: true
+    });
+
+    const latency = sent.createdTimestamp - interaction.createdTimestamp;
+    await interaction.editReply(`Pong! Latency: ${latency}ms`);
+  }
+};
+```
+
+```javascript
+// src/events/interactionCreate.js
+const { Events } = require('discord.js');
+
+module.exports = {
+  name: Events.InteractionCreate,
+  async execute(interaction) {
+    if (!interaction.isChatInputCommand()) return;
+
+    const command = interaction.client.commands.get(interaction.commandName);
+    if (!command) {
+      console.error(`No command matching ${interaction.commandName}`);
+      return;
+    }
+
+    try {
+      await command.execute(interaction);
+    } catch (error) {
+      console.error(error);
+      const reply = {
+        content: 'There was an error executing this command!',
+        ephemeral: true
+      };
+
+      if (interaction.replied || interaction.deferred) {
+        await interaction.followUp(reply);
+      } else {
+        await interaction.reply(reply);
+      }
+    }
+  }
+};
+```
+
+```javascript
+// src/deploy-commands.js
+const { REST, Routes } = require('discord.js');
+const fs = require('node:fs');
+const path = require('node:path');
+require('dotenv').config();
+
+const commands = [];
+const commandsPath = path.join(__dirname, 'commands');
+const commandFiles = fs.readdirSync(commandsPath).filter(f => f.endsWith('.js'));
+
+for (const file of commandFiles) {
+  const command = require(path.join(commandsPath, file));
+  commands.push(command.data.toJSON());
+}
+
+const rest = new REST().setToken(process.env.DISCORD_TOKEN);
+
+(async () => {
+  try {
+    console.log(`Refreshing ${commands.length} commands...`);
+
+    // Guild commands (instant, for testing)
+    // const data = await rest.put(
+    //   Routes.applicationGuildCommands(CLIENT_ID, GUILD_ID),
+    //   { body: commands }
+    // );
+
+    // Global commands (can take up to 1 hour to propagate)
+    const data = await rest.put(
+      Routes.applicationCommands(process.env.CLIENT_ID),
+      { body: commands }
+    );
+
+    console.log(`Successfully registered ${data.length} commands`);
+  } catch (error) {
+    console.error(error);
+  }
+})();
+```
+
+### Structure
+
+discord-bot/
+├── src/
+│   ├── index.js           # Main entry point
+│   ├── deploy-commands.js # Command registration script
+│   ├── commands/          # Slash command handlers
+│   │   └── ping.js
+│   └── events/            # Event handlers
+│       ├── ready.js
+│       └── interactionCreate.js
+├── .env
+└── package.json
+
+### Pycord Bot Foundation
+
+Discord bot with Pycord (Python) and application commands
+
+**When to use**: Building Discord bots with Python,Prefer async/await patterns,Need good slash command support
+
+```python
+# main.py
+import os
+import discord
+from discord.ext import commands
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Configure intents - only enable what you need
+intents = discord.Intents.default()
+# intents.message_content = True  # PRIVILEGED - avoid if possible
+# intents.members = True          # PRIVILEGED
+
+bot = commands.Bot(
+    command_prefix="!",  # Legacy, prefer slash commands
+    intents=intents
+)
+
+@bot.event
+async def on_ready():
+    print(f"Logged in as {bot.user}")
+    # Sync commands (do this carefully - see sharp edges)
+    # await bot.sync_commands()
+
+# Slash command
+@bot.slash_command(name="ping", description="Check bot latency")
+async def ping(ctx: discord.ApplicationContext):
+    latency = round(bot.latency * 1000)
+    await ctx.respond(f"Pong! Latency: {latency}ms")
+
+# Slash command with options
+@bot.slash_command(name="greet", description="Greet a user")
+async def greet(
+    ctx: discord.ApplicationContext,
+    user: discord.Option(discord.Member, "User to greet"),
+    message: discord.Option(str, "Custom message", required=False)
+):
+    msg = message or "Hello!"
+    await ctx.respond(f"{user.mention}, {msg}")
+
+# Load cogs
+for filename in os.listdir("./cogs"):
+    if filename.endswith(".py"):
+        bot.load_extension(f"cogs.{filename[:-3]}")
+
+bot.run(os.environ["DISCORD_TOKEN"])
+```
+
+```python
+# cogs/general.py
+import discord
+from discord.ext import commands
+
+class General(commands.Cog):
+    def __init__(self, bot):
+        self.bot = bot
+
+    @commands.slash_command(name="info", description="Bot information")
+    async def info(self, ctx: discord.ApplicationContext):
+        embed = discord.Embed(
+            title="Bot Info",
+            description="A helpful Discord bot",
+            color=discord.Color.blue()
+        )
+        embed.add_field(name="Servers", value=len(self.bot.guilds))
+        embed.add_field(name="Latency", value=f"{round(self.bot.latency * 1000)}ms")
+        await ctx.respond(embed=embed)
+
+    @commands.Cog.listener()
+    async def on_member_join(self, member: discord.Member):
+        # Requires Members intent (PRIVILEGED)
+        channel = member.guild.system_channel
+        if channel:
+            await channel.send(f"Welcome {member.mention}!")
+
+def setup(bot):
+    bot.add_cog(General(bot))
+```
+
+### Structure
+
+discord-bot/
+├── main.py           # Main bot file
+├── cogs/             # Command groups
+│   └── general.py
+├── .env
+└── requirements.txt
+
+### Interactive Components Pattern
+
+Using buttons, select menus, and modals for rich UX
+
+**When to use**: Need interactive user interfaces,Collecting user input beyond slash command options,Building menus, confirmations, or forms
+
+```javascript
+// Discord.js - Buttons and Select Menus
+const {
+  SlashCommandBuilder,
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  StringSelectMenuBuilder,
+  ModalBuilder,
+  TextInputBuilder,
+  TextInputStyle
+} = require('discord.js');
+
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName('menu')
+    .setDescription('Shows an interactive menu'),
+
+  async execute(interaction) {
+    // Button row
+    const buttonRow = new ActionRowBuilder()
+      .addComponents(
+        new ButtonBuilder()
+          .setCustomId('confirm')
+          .setLabel('Confirm')
+          .setStyle(ButtonStyle.Primary),
+        new ButtonBuilder()
+          .setCustomId('cancel')
+          .setLabel('Cancel')
+          .setStyle(ButtonStyle.Danger),
+        new ButtonBuilder()
+          .setLabel('Documentation')
+          .setURL('https://discord.js.org')
+          .setStyle(ButtonStyle.Link)  // Link buttons don't emit events
+      );
+
+    // Select menu row (one per row, takes all 5 slots)
+    const selectRow = new ActionRowBuilder()
+      .addComponents(
+        new StringSelectMenuBuilder()
+          .setCustomId('select-role')
+          .setPlaceholder('Select a role')
+          .setMinValues(1)
+          .setMaxValues(3)
+          .addOptions([
+            { label: 'Developer', value: 'dev', emoji: '💻' },
+            { label: 'Designer', value: 'design', emoji: '🎨' },
+            { label: 'Community', value: 'community', emoji: '🎉' }
+          ])
+      );
+
+    await interaction.reply({
+      content: 'Choose an option:',
+      components: [buttonRow, selectRow]
+    });
+
+    // Collect responses
+    const collector = interaction.channel.createMessageComponentCollector({
+      filter: i => i.user.id === interaction.user.id,
+      time: 60_000  // 60 seconds timeout
+    });
+
+    collector.on('collect', async i => {
+      if (i.customId === 'confirm') {
+        await i.update({ content: 'Confirmed!', components: [] });
+        collector.stop();
+      } else if (i.customId === 'cancel') {
+        await i.update({ content: 'Cancelled', components: [] });
+        collector.stop();
+      } else if (i.customId === 'select-role') {
+        await i.update({ content: `You selected: ${i.values.join(', ')}` });
+      }
+    });
+  }
+};
+```
+
+```javascript
+// Modals (forms)
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName('feedback')
+    .setDescription('Submit feedback'),
+
+  async execute(interaction) {
+    const modal = new ModalBuilder()
+      .setCustomId('feedback-modal')
+      .setTitle('Submit Feedback');
+
+    const titleInput = new TextInputBuilder()
+      .setCustomId('feedback-title')
+      .setLabel('Title')
+      .setStyle(TextInputStyle.Short)
+      .setRequired(true)
+      .setMaxLength(100);
+
+    const bodyInput = new TextInputBuilder()
+      .setCustomId('feedback-body')
+      .setLabel('Your feedback')
+      .setStyle(TextInputStyle.Paragraph)
+      .setRequired(true)
+      .setMaxLength(1000)
+      .setPlaceholder('Describe your feedback...');
+
+    modal.addComponents(
+      new ActionRowBuilder().addComponents(titleInput),
+      new ActionRowBuilder().addComponents(bodyInput)
+    );
+
+    // Show modal - MUST be first response
+    await interaction.showModal(modal);
+  }
+};
+
+// Handle modal submission in interactionCreate
+if (interaction.isModalSubmit()) {
+  if (interaction.customId === 'feedback-modal') {
+    const title = interaction.fields.getTextInputValue('feedback-title');
+    const body = interaction.fields.getTextInputValue('feedback-body');
+
+    await interaction.reply({
+      content: `Thanks for your feedback!\n**${title}**\n${body}`,
+      ephemeral: true
+    });
+  }
+}
+```
+
+```python
+# Pycord - Buttons and Views
+import discord
+
+class ConfirmView(discord.ui.View):
+    def __init__(self):
+        super().__init__(timeout=60)
+        self.value = None
+
+    @discord.ui.button(label="Confirm", style=discord.ButtonStyle.green)
+    async def confirm(self, button, interaction):
+        self.value = True
+        await interaction.response.edit_message(content="Confirmed!", view=None)
+        self.stop()
+
+    @discord.ui.button(label="Cancel", style=discord.ButtonStyle.red)
+    async def cancel(self, button, interaction):
+        self.value = False
+        await interaction.response.edit_message(content="Cancelled", view=None)
+        self.stop()
+
+@bot.slash_command(name="confirm")
+async def confirm_cmd(ctx: discord.ApplicationContext):
+    view = ConfirmView()
+    await ctx.respond("Are you sure?", view=view)
+
+    await view.wait()  # Wait for user interaction
+    if view.value is None:
+        await ctx.followup.send("Timed out")
+
+# Select Menu
+class RoleSelect(discord.ui.Select):
+    def __init__(self):
+        options = [
+            discord.SelectOption(label="Developer", value="dev", emoji="💻"),
+            discord.SelectOption(label="Designer", value="design", emoji="🎨"),
+        ]
+        super().__init__(
+            placeholder="Select roles...",
+            min_values=1,
+            max_values=2,
+            options=options
+        )
+
+    async def callback(self, interaction):
+        await interaction.response.send_message(
+            f"You selected: {', '.join(self.values)}",
+            ephemeral=True
+        )
+
+class RoleView(discord.ui.View):
+    def __init__(self):
+        super().__init__()
+        self.add_item(RoleSelect())
+
+# Modal
+class FeedbackModal(discord.ui.Modal):
+    def __init__(self):
+        super().__init__(title="Submit Feedback")
+
+        self.add_item(discord.ui.InputText(
+            label="Title",
+            style=discord.InputTextStyle.short,
+            required=True,
+            max_length=100
+        ))
+        self.add_item(discord.ui.InputText(
+            label="Feedback",
+            style=discord.InputTextStyle.long,
+            required=True,
+            max_length=1000
+        ))
+
+    async def callback(self, interaction):
+        title = self.children[0].value
+        body = self.children[1].value
+        await interaction.response.send_message(
+            f"Thanks!\n**{title}**\n{body}",
+            ephemeral=True
+        )
+
+@bot.slash_command(name="feedback")
+async def feedback(ctx: discord.ApplicationContext):
+    await ctx.send_modal(FeedbackModal())
+```
+
+### Limits
+
+- 5 ActionRows per message/modal
+- 5 buttons per ActionRow
+- 1 select menu per ActionRow (takes all 5 slots)
+- 5 select menus max per message
+- 25 options per select menu
+- Modal must be first response (cannot defer first)
+
+### Deferred Response Pattern
+
+Handle slow operations without timing out
+
+**When to use**: Operation takes more than 3 seconds,Database queries, API calls, LLM responses,File processing or generation
+
+```javascript
+// Discord.js - Deferred response
+module.exports = {
+  data: new SlashCommandBuilder()
+    .setName('slow-task')
+    .setDescription('Performs a slow operation'),
+
+  async execute(interaction) {
+    // Defer immediately - you have 3 seconds!
+    await interaction.deferReply();
+    // For ephemeral: await interaction.deferReply({ ephemeral: true });
+
+    try {
+      // Now you have 15 minutes to complete
+      const result = await slowDatabaseQuery();
+      const aiResponse = await callOpenAI(result);
+
+      // Edit the deferred reply
+      await interaction.editReply({
+        content: `Result: ${aiResponse}`,
+        embeds: [resultEmbed]
+      });
+    } catch (error) {
+      await interaction.editReply({
+        content: 'An error occurred while processing your request.'
+      });
+    }
+  }
+};
+
+// For components (buttons, select menus)
+collector.on('collect', async i => {
+  await i.deferUpdate();  // Acknowledge without visual change
+  // Or: await i.deferReply({ ephemeral: true });
+
+  const result = await slowOperation();
+  await i.editReply({ content: result });
+});
+```
+
+```python
+# Pycord - Deferred response
+@bot.slash_command(name="slow-task")
+async def slow_task(ctx: discord.ApplicationContext):
+    # Defer immediately
+    await ctx.defer()
+    # For ephemeral: await ctx.defer(ephemeral=True)
+
+    try:
+        result = await slow_database_query()
+        ai_response = await call_openai(result)
+
+        await ctx.followup.send(f"Result: {ai_response}")
+    except Exception as e:
+        await ctx.followup.send("An error occurred")
+```
+
+### Timing
+
+- Initial_response: 3 seconds
+- Deferred_followup: 15 minutes
+- Ephemeral_note: Can only be set on initial response, not changed later
+
+### Embed Builder Pattern
+
+Rich embedded messages for professional-looking content
+
+**When to use**: Displaying formatted information,Status updates, help menus, logs,Data with structure (fields, images)
+
+```javascript
+const { EmbedBuilder, Colors } = require('discord.js');
+
+// Basic embed
+const embed = new EmbedBuilder()
+  .setColor(Colors.Blue)
+  .setTitle('Bot Status')
+  .setURL('https://example.com')
+  .setAuthor({
+    name: 'Bot Name',
+    iconURL: client.user.displayAvatarURL()
+  })
+  .setDescription('Current status and statistics')
+  .addFields(
+    { name: 'Servers', value: `${client.guilds.cache.size}`, inline: true },
+    { name: 'Users', value: `${client.users.cache.size}`, inline: true },
+    { name: 'Uptime', value: formatUptime(), inline: true }
+  )
+  .setThumbnail(client.user.displayAvatarURL())
+  .setImage('https://example.com/banner.png')
+  .setTimestamp()
+  .setFooter({
+    text: 'Requested by User',
+    iconURL: interaction.user.displayAvatarURL()
+  });
+
+await interaction.reply({ embeds: [embed] });
+
+// Multiple embeds (max 10)
+await interaction.reply({ embeds: [embed1, embed2, embed3] });
+```
+
+```python
+# Pycord
+embed = discord.Embed(
+    title="Bot Status",
+    description="Current status and statistics",
+    color=discord.Color.blue(),
+    url="https://example.com"
+)
+embed.set_author(
+    name="Bot Name",
+    icon_url=bot.user.display_avatar.url
+)
+embed.add_field(name="Servers", value=len(bot.guilds), inline=True)
+embed.add_field(name="Users", value=len(bot.users), inline=True)
+embed.set_thumbnail(url=bot.user.display_avatar.url)
+embed.set_image(url="https://example.com/banner.png")
+embed.set_footer(text="Requested by User", icon_url=ctx.author.display_avatar.url)
+embed.timestamp = discord.utils.utcnow()
+
+await ctx.respond(embed=embed)
+```
+
+### Limits
+
+- 10 embeds per message
+- 6000 characters total across all embeds
+- 256 characters for title
+- 4096 characters for description
+- 25 fields per embed
+- 256 characters per field name
+- 1024 characters per field value
+
+### Rate Limit Handling Pattern
+
+Gracefully handle Discord API rate limits
+
+**When to use**: High-volume operations,Bulk messaging or role assignments,Any repeated API calls
+
+```javascript
+// Discord.js handles rate limits automatically, but for custom handling:
+const { REST } = require('discord.js');
+
+const rest = new REST({ version: '10' })
+  .setToken(process.env.DISCORD_TOKEN);
+
+rest.on('rateLimited', (info) => {
+  console.log(`Rate limited! Retry after ${info.retryAfter}ms`);
+  console.log(`Route: ${info.route}`);
+  console.log(`Global: ${info.global}`);
+});
+
+// Queue pattern for bulk operations
+class RateLimitQueue {
+  constructor() {
+    this.queue = [];
+    this.processing = false;
+    this.requestsPerSecond = 40; // Safe margin below 50
+  }
+
+  async add(operation) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ operation, resolve, reject });
+      this.process();
+    });
+  }
+
+  async process() {
+    if (this.processing || this.queue.length === 0) return;
+    this.processing = true;
+
+    while (this.queue.length > 0) {
+      const { operation, resolve, reject } = this.queue.shift();
+
+      try {
+        const result = await operation();
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      }
+
+      // Throttle: ~40 requests per second
+      await new Promise(r => setTimeout(r, 1000 / this.requestsPerSecond));
+    }
+
+    this.processing = false;
+  }
+}
+
+const queue = new RateLimitQueue();
+
+// Usage: Send 200 messages without hitting rate limits
+for (const user of users) {
+  await queue.add(() => user.send('Welcome!'));
+}
+```
+
+```python
+# Pycord/discord.py handles rate limits automatically
+# For custom handling:
+import asyncio
+from collections import deque
+
+class RateLimitQueue:
+    def __init__(self, requests_per_second=40):
+        self.queue = deque()
+        self.processing = False
+        self.delay = 1 / requests_per_second
+
+    async def add(self, coro):
+        future = asyncio.Future()
+        self.queue.append((coro, future))
+        if not self.processing:
+            asyncio.create_task(self._process())
+        return await future
+
+    async def _process(self):
+        self.processing = True
+        while self.queue:
+            coro, future = self.queue.popleft()
+            try:
+                result = await coro
+                future.set_result(result)
+            except Exception as e:
+                future.set_exception(e)
+            await asyncio.sleep(self.delay)
+        self.processing = False
+
+queue = RateLimitQueue()
+
+# Usage
+for member in guild.members:
+    await queue.add(member.send("Welcome!"))
+```
+
+### Rate_limits
+
+- Global: 50 requests per second
+- Gateway: 120 requests per 60 seconds
+- Specific: Messages to same channel: 5/5s, Bulk delete: 1/1s, Guild member requests: varies by guild size
+
+### Sharding Pattern
+
+Scale bots to 2500+ servers with sharding
+
+**When to use**: Bot approaching 2500 guilds (required),Want horizontal scaling,Memory optimization for large bots
+
+```javascript
+// Discord.js Sharding Manager
+// shard.js (main entry)
+const { ShardingManager } = require('discord.js');
+
+const manager = new ShardingManager('./bot.js', {
+  token: process.env.DISCORD_TOKEN,
+  totalShards: 'auto',  // Discord determines optimal count
+  // Or specify: totalShards: 4
+});
+
+manager.on('shardCreate', shard => {
+  console.log(`Launched shard ${shard.id}`);
+
+  shard.on('ready', () => {
+    console.log(`Shard ${shard.id} ready`);
+  });
+
+  shard.on('disconnect', () => {
+    console.log(`Shard ${shard.id} disconnected`);
+  });
+});
+
+manager.spawn();
+
+// bot.js - Modified for sharding
+const { Client } = require('discord.js');
+
+const client = new Client({ intents: [...] });
+
+// Get shard info
+client.on('ready', () => {
+  console.log(`Shard ${client.shard.ids[0]} ready with ${client.guilds.cache.size} guilds`);
+});
+
+// Cross-shard data
+async function getTotalGuilds() {
+  const results = await client.shard.fetchClientValues('guilds.cache.size');
+  return results.reduce((acc, count) => acc + count, 0);
+}
+
+// Broadcast to all shards
+async function broadcastMessage(channelId, message) {
+  await client.shard.broadcastEval(
+    (c, { channelId, message }) => {
+      const channel = c.channels.cache.get(channelId);
+      if (channel) channel.send(message);
+    },
+    { context: { channelId, message } }
+  );
+}
+```
+
+```python
+# Pycord - AutoShardedBot
+import discord
+from discord.ext import commands
+
+# Automatically handles sharding
+bot = commands.AutoShardedBot(
+    command_prefix="!",
+    intents=discord.Intents.default(),
+    shard_count=None  # Auto-determine
+)
+
+@bot.event
+async def on_ready():
+    print(f"Logged in on {len(bot.shards)} shards")
+    for shard_id, shard in bot.shards.items():
+        print(f"Shard {shard_id}: {shard.latency * 1000:.2f}ms")
+
+@bot.event
+async def on_shard_ready(shard_id):
+    print(f"Shard {shard_id} is ready")
+
+# Get guilds per shard
+for shard_id, guilds in bot.guilds_by_shard().items():
+    print(f"Shard {shard_id}: {len(guilds)} guilds")
+```
+
+### Scaling_guide
+
+- 1-2500 guilds: No sharding required
+- 2500+ guilds: Sharding required by Discord
+- Recommended: ~1000 guilds per shard
+- Memory: Each shard runs in separate process
+
+
+## Sharp Edges
+
+### Interaction Timeout (3 Second Rule)
+
+Severity: CRITICAL
+
+Situation: Handling slash commands, buttons, select menus, or modals
+
+Symptoms:
+User sees "This interaction failed" or "The application did not respond."
+Command works locally but fails in production.
+Slow operations never complete.
+
+Why this breaks:
+Discord requires ALL interactions to be acknowledged within 3 seconds:
+- Slash commands
+- Button clicks
+- Select menu selections
+- Context menu commands
+
+If you do ANY slow operation (database, API, file I/O) before responding,
+you'll miss the window. Discord shows an error even if your bot processes
+the request correctly afterward.
+
+After acknowledgment, you have 15 minutes for follow-up responses.
+
+Recommended fix:
+
+
+## Acknowledge immediately, process later
+
+```javascript
+// Discord.js - Defer for slow operations
+module.exports = {
+  async execute(interaction) {
+    // DEFER IMMEDIATELY - before any slow operation
+    await interaction.deferReply();
+    // For ephemeral: await interaction.deferReply({ ephemeral: true });
+
+    // Now you have 15 minutes
+    const result = await slowDatabaseQuery();
+    const aiResponse = await callLLM(result);
+
+    // Edit the deferred reply
+    await interaction.editReply(`Result: ${aiResponse}`);
+  }
+};
+```
+
+```python
+# Pycord
+@bot.slash_command()
+async def slow_command(ctx):
+    await ctx.defer()  # Acknowledge immediately
+    # await ctx.defer(ephemeral=True)  # For private response
+
+    result = await slow_operation()
+    await ctx.followup.send(f"Result: {result}")
+```
+
+
+## For components (buttons, menus)
+
+```javascript
+// If you're updating the message
+await interaction.deferUpdate();
+
+// If you're sending a new response
+await interaction.deferReply({ ephemeral: true });
+```
+
+### Missing Privileged Intent Configuration
+
+Severity: CRITICAL
+
+Situation: Bot needs member data, presences, or message content
+
+Symptoms:
+Members intent: member lists empty, on_member_join doesn't fire
+Presences intent: statuses always unknown/offline
+Message content intent: message.content is empty string
+
+Why this breaks:
+Discord has 3 privileged intents that require manual enablement:
+1. **GUILD_MEMBERS** - Member join/leave, member lists
+2. **GUILD_PRESENCES** - Online status, activities
+3. **MESSAGE_CONTENT** - Read message text (deprecated for commands)
+
+These must be:
+1. Enabled in Discord Developer Portal > Bot > Privileged Gateway Intents
+2. Requested in your bot code
+
+At 100+ servers, you need Discord verification to keep using them.
+
+Recommended fix:
+
+
+## Step 1: Enable in Developer Portal
+
+```
+1. Go to https://discord.com/developers/applications
+2. Select your application
+3. Go to Bot section
+4. Scroll to Privileged Gateway Intents
+5. Toggle ON the intents you need
+```
+
+
+## Step 2: Request in code
+
+```javascript
+// Discord.js
+const { Client, GatewayIntentBits } = require('discord.js');
+
+const client = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMembers,       // PRIVILEGED
+    // GatewayIntentBits.GuildPresences,  // PRIVILEGED
+    // GatewayIntentBits.MessageContent,  // PRIVILEGED - avoid!
+  ]
+});
+```
+
+```python
+# Pycord
+intents = discord.Intents.default()
+intents.members = True       # PRIVILEGED
+# intents.presences = True   # PRIVILEGED
+# intents.message_content = True  # PRIVILEGED - avoid!
+
+bot = commands.Bot(intents=intents)
+```
+
+
+## Avoid Message Content Intent if possible
+
+Use slash commands, buttons, and modals instead of message parsing.
+These don't require the Message Content intent.
+
+### Command Registration Rate Limited
+
+Severity: HIGH
+
+Situation: Registering slash commands
+
+Symptoms:
+Commands not appearing. 429 errors when deploying.
+"You are being rate limited" messages.
+Commands appear for some guilds but not others.
+
+Why this breaks:
+Command registration is rate limited:
+- Global commands: 200 creates/day, updates take up to 1 hour to propagate
+- Guild commands: 200 creates/day per guild, instant update
+
+Common mistakes:
+- Registering commands on every bot startup
+- Registering in every guild separately
+- Making changes in a loop without delays
+
+Recommended fix:
+
+
+## Use a separate deploy script (not on startup)
+
+```javascript
+// deploy-commands.js - Run manually, not on bot start
+const { REST, Routes } = require('discord.js');
+
+const rest = new REST().setToken(process.env.DISCORD_TOKEN);
+
+async function deploy() {
+  // For development: Guild commands (instant)
+  if (process.env.GUILD_ID) {
+    await rest.put(
+      Routes.applicationGuildCommands(
+        process.env.CLIENT_ID,
+        process.env.GUILD_ID
+      ),
+      { body: commands }
+    );
+    console.log('Guild commands deployed instantly');
+  }
+
+  // For production: Global commands (up to 1 hour)
+  else {
+    await rest.put(
+      Routes.applicationCommands(process.env.CLIENT_ID),
+      { body: commands }
+    );
+    console.log('Global commands deployed (may take up to 1 hour)');
+  }
+}
+
+deploy();
+```
+
+```python
+# Pycord - Don't sync on every startup
+@bot.event
+async def on_ready():
+    # DON'T DO THIS:
+    # await bot.sync_commands()
+
+    print(f"Ready! Commands should already be registered.")
+
+# Instead, sync manually or use a flag
+if __name__ == "__main__":
+    if "--sync" in sys.argv:
+        # Only sync when explicitly requested
+        bot.sync_commands_on_start = True
+    bot.run(token)
+```
+
+
+## Testing workflow
+
+1. Use guild commands during development (instant updates)
+2. Only deploy global commands when ready for production
+3. Run deploy script manually, not on every restart
+
+### Bot Token Exposed
+
+Severity: CRITICAL
+
+Situation: Storing or sharing bot token
+
+Symptoms:
+Unauthorized actions from your bot.
+Bot joins random servers.
+Bot sends spam or malicious content.
+"Invalid token" after Discord invalidates it.
+
+Why this breaks:
+Your bot token provides FULL control over your bot. Attackers can:
+- Send messages as your bot
+- Join servers, create invites
+- Access all data your bot can access
+- Potentially take over servers where bot has admin
+
+Discord actively scans GitHub for exposed tokens and invalidates them.
+Common exposure points:
+- Committed to Git
+- Shared in Discord itself
+- In client-side code
+- In public screenshots
+
+Recommended fix:
+
+
+## Never hardcode tokens
+
+```javascript
+// BAD - never do this
+const token = 'MTIzNDU2Nzg5MDEyMzQ1Njc4.ABCDEF.xyz...';
+
+// GOOD - environment variables
+require('dotenv').config();
+client.login(process.env.DISCORD_TOKEN);
+```
+
+
+## Use .gitignore
+
+```
+# .gitignore
+.env
+.env.local
+config.json
+```
+
+
+## If token is exposed
+
+1. Go to Developer Portal immediately
+2. Regenerate the token
+3. Update all deployments
+4. Review bot activity for unauthorized actions
+5. Check git history and force push to remove if needed
+
+
+## Use environment variables properly
+
+```bash
+# .env (never commit)
+DISCORD_TOKEN=your_token_here
+CLIENT_ID=your_client_id
+```
+
+```javascript
+// Load with dotenv
+require('dotenv').config();
+const token = process.env.DISCORD_TOKEN;
+```
+
+### Bot Missing applications.commands Scope
+
+Severity: HIGH
+
+Situation: Slash commands not appearing for users
+
+Symptoms:
+Bot is in server but slash commands don't show up.
+Typing / shows no commands from your bot.
+Commands worked in development server but not others.
+
+Why this breaks:
+Discord has two important OAuth scopes:
+- `bot` - Traditional bot permissions (messages, reactions, etc.)
+- `applications.commands` - Slash command permissions
+
+Many bots were invited with only the `bot` scope before slash commands
+existed. They need to be re-invited with both scopes.
+
+Recommended fix:
+
+
+## Generate correct invite URL
+
+```
+https://discord.com/api/oauth2/authorize
+  ?client_id=YOUR_CLIENT_ID
+  &permissions=0
+  &scope=bot%20applications.commands
+```
+
+
+## In Discord Developer Portal
+
+1. Go to OAuth2 > URL Generator
+2. Select BOTH:
+   - `bot`
+   - `applications.commands`
+3. Select required bot permissions
+4. Use generated URL
+
+
+## Re-invite without kicking
+
+Users can use the new invite URL even if bot is already in server.
+This adds the new scope without removing the bot.
+
+```javascript
+// Generate invite URL in code
+const inviteUrl = client.generateInvite({
+  scopes: ['bot', 'applications.commands'],
+  permissions: [
+    'SendMessages',
+    'EmbedLinks',
+    // Add other needed permissions
+  ]
+});
+```
+
+### Global Commands Not Appearing Immediately
+
+Severity: MEDIUM
+
+Situation: Deploying global slash commands
+
+Symptoms:
+Commands don't appear after deployment.
+Guild commands work but global commands don't.
+Commands appear after an hour.
+
+Why this breaks:
+Global commands can take up to 1 hour to propagate to all Discord servers.
+This is by design for Discord's caching and CDN.
+
+Guild commands are instant but only work in that specific guild.
+
+Recommended fix:
+
+
+## Development: Use guild commands
+
+```javascript
+// Instant updates for testing
+await rest.put(
+  Routes.applicationGuildCommands(CLIENT_ID, GUILD_ID),
+  { body: commands }
+);
+```
+
+
+## Production: Deploy global commands during off-peak
+
+```javascript
+// Takes up to 1 hour to propagate
+await rest.put(
+  Routes.applicationCommands(CLIENT_ID),
+  { body: commands }
+);
+```
+
+
+## Workflow
+
+1. Develop and test with guild commands (instant)
+2. When ready, deploy global commands
+3. Wait up to 1 hour for propagation
+4. Don't deploy global commands frequently
+
+### Frequent Gateway Disconnections
+
+Severity: MEDIUM
+
+Situation: Bot randomly goes offline or misses events
+
+Symptoms:
+Bot shows as offline intermittently.
+Events are missed (member joins, messages).
+Reconnection messages in logs.
+
+Why this breaks:
+Discord gateway requires regular heartbeats. Issues:
+- Blocking operations prevent heartbeat
+- Network instability
+- Memory pressure causing GC pauses
+- Too many guilds without sharding (2500+ requires sharding)
+
+Recommended fix:
+
+
+## Never block the event loop
+
+```javascript
+// BAD - blocks event loop
+const data = fs.readFileSync('file.json');
+
+// GOOD - async
+const data = await fs.promises.readFile('file.json');
+```
+
+
+## Handle reconnections gracefully
+
+```javascript
+client.on('shardResume', (id, replayedEvents) => {
+  console.log(`Shard ${id} resumed, replayed ${replayedEvents} events`);
+});
+
+client.on('shardDisconnect', (event, id) => {
+  console.log(`Shard ${id} disconnected`);
+});
+
+client.on('shardReconnecting', (id) => {
+  console.log(`Shard ${id} reconnecting...`);
+});
+```
+
+
+## Implement sharding at scale
+
+```javascript
+// Required at 2500+ guilds
+const manager = new ShardingManager('./bot.js', {
+  token: process.env.DISCORD_TOKEN,
+  totalShards: 'auto'
+});
+manager.spawn();
+```
+
+### Modal Must Be First Response
+
+Severity: MEDIUM
+
+Situation: Showing a modal from a slash command or button
+
+Symptoms:
+"Interaction has already been acknowledged" error.
+Modal doesn't appear.
+Works sometimes but not others.
+
+Why this breaks:
+Modals have a special requirement: showing a modal MUST be the first
+response to an interaction. You cannot:
+- defer() then showModal()
+- reply() then showModal()
+- Think for more than 3 seconds then showModal()
+
+Recommended fix:
+
+
+## Show modal immediately
+
+```javascript
+// CORRECT - modal is first response
+async execute(interaction) {
+  const modal = new ModalBuilder()
+    .setCustomId('my-modal')
+    .setTitle('Input Form');
+
+  // Show immediately - no defer, no reply first
+  await interaction.showModal(modal);
+}
+```
+
+```javascript
+// WRONG - deferred first
+async execute(interaction) {
+  await interaction.deferReply();  // CAN'T DO THIS
+  await interaction.showModal(modal);  // Will fail
+}
+```
+
+
+## If you need to check something first
+
+```javascript
+async execute(interaction) {
+  // Quick sync check is OK (under 3 seconds)
+  if (!hasPermission(interaction.user.id)) {
+    return interaction.reply({
+      content: 'No permission',
+      ephemeral: true
+    });
+  }
+
+  // Show modal (still first interaction response for this path)
+  await interaction.showModal(modal);
+}
+```
+
+
+## Validation Checks
+
+### Hardcoded Discord Token
+
+Severity: ERROR
+
+Discord tokens must never be hardcoded
+
+Message: Hardcoded Discord token detected. Use environment variables.
+
+### Token Variable Assignment
+
+Severity: ERROR
+
+Tokens should come from environment, not strings
+
+Message: Token assigned from string literal. Use environment variable.
+
+### Token in Client-Side Code
+
+Severity: ERROR
+
+Never expose Discord tokens to browsers
+
+Message: Discord credentials exposed client-side. Only use server-side.
+
+### Slow Operation Without Defer
+
+Severity: WARNING
+
+Slow operations should be deferred to avoid timeout
+
+Message: Slow operation without defer. Interaction may timeout.
+
+### Interaction Without Error Handling
+
+Severity: WARNING
+
+Interactions should have try/catch for graceful errors
+
+Message: Interaction without error handling. Add try/catch.
+
+### Using Message Content Intent
+
+Severity: WARNING
+
+Message Content is privileged, prefer slash commands
+
+Message: Using Message Content intent. Consider slash commands instead.
+
+### Requesting All Intents
+
+Severity: WARNING
+
+Only request intents you actually need
+
+Message: Requesting all intents. Only enable what you need.
+
+### Syncing Commands on Ready Event
+
+Severity: WARNING
+
+Don't sync commands on every bot startup
+
+Message: Syncing commands on startup. Use separate deploy script.
+
+### Registering Commands in Loop
+
+Severity: WARNING
+
+Use bulk registration, not individual calls
+
+Message: Registering commands in loop. Use bulk registration.
+
+### No Rate Limit Handling
+
+Severity: INFO
+
+Consider handling rate limits for bulk operations
+
+Message: Bulk operation without rate limit handling.
+
+
+## Collaboration
+
+### Delegation Triggers
+
+- user needs AI-powered Discord bot -> llm-architect (Integrate LLM for conversational Discord bot)
+- user needs Slack integration too -> slack-bot-builder (Cross-platform bot architecture)
+- user needs voice features -> voice-agents (Discord voice channel integration)
+- user needs database for bot data -> postgres-wizard (Store user data, server configs, moderation logs)
+- user needs workflow automation -> workflow-automation (Discord events trigger workflows)
+- user needs high availability -> devops (Sharding, scaling, monitoring for large bots)
+- user needs payment integration -> stripe-specialist (Premium bot features, subscription management)