Discord Bot Stinger

---
name: "discord-bot-stinger"
description: "Build Discord bots. Use for slash commands, modals, voice, gateway design, rate limits, or verification. Read README.md for the guide map."
license: AGPL-3.0-or-later
---

# discord-bot-stinger

Start with [README.md](README.md) for the workflow map and detailed references.

Equips `discord-bot-wasp-drone` to build, review, and audit Discord bots and applications on the 2026 Discord API surface. Read this file first on every invocation, then follow the guide pointer for the specific task.

---

## Quick-reference: critical API facts (May 2026)

| Fact | Value | Source |
|------|-------|--------|
| discord.js stable | **v14.25.1** (v15 pre-release, ~94% milestone; not production-ready) | `research/external/2026-05-20-discordjs-v15-status.md` |
| discord.py stable | **v2.x** (CommandTree + app_commands) | `research/external/2026-05-20-discordpy-app-commands.md` |
| Wavelink status | **ABANDONED**: do not recommend | `research/external/2026-05-20-wavelink-deprecated.md` |
| Voice clients (Python) | **Mafic** or **lavalink.py** (both DAVE-compliant) | `research/external/2026-05-20-lavalink-clients-2026.md` |
| Voice clients (Node.js) | **Shoukaku** or **Lavalink-Client** (both DAVE-compliant) | `research/external/2026-05-20-lavalink-clients-2026.md` |
| Lavalink version | **v4** | `research/external/2026-05-20-lavalink-clients-2026.md` |
| DAVE protocol | Mandatory in all voice channels since **March 1, 2026** | `research/external/2026-05-20-discord-changelog-2026.md` |
| Discord API version | **v10** (Gateway v10) | `research/external/2026-05-20-discord-api-v10-changes-2026.md` |
| Sharding required at | **2,500 guilds** (hard enforcement) | `research/external/2026-05-20-discord-sharding-guide.md` |
| Privileged intent gate | Apply at **75 servers**; hard block at **100** | `research/external/2026-05-20-discord-privileged-intents.md` |
| Data retention limit | **30 days** max for privileged intent approval | `research/external/2026-05-20-discord-privileged-intents.md` |
| Global command propagation | **~1 hour** | `research/external/2026-05-20-discord-application-commands-spec.md` |
| Guild command propagation | **Instant**: use in dev | `research/external/2026-05-20-discord-application-commands-spec.md` |
| Modal custom_id max | **100 characters** | `research/external/2026-05-20-discord-components-modals.md` |
| Buttons per message | **25 max** (5 action rows × 5 buttons) | `research/external/2026-05-20-discord-components-modals.md` |
| Node.js minimum | **22.12.0** for discord.js | `research/external/2026-05-20-discordjs-v14-slash-commands.md` |

---

## Critical directives (non-negotiables)

Every code sample, review comment, and recommendation from this stinger must respect:

1. **Never hardcode bot tokens or client secrets.** Use `process.env.DISCORD_TOKEN` (JS) or `os.environ["DISCORD_TOKEN"]` (Python). Tokens committed to source are harvested by secret-scanning bots immediately.
2. **Always specify the minimum required Gateway Intents.** Over-privileged intents trigger the Privileged Intent approval gate, slow verification, and increase PII exposure. See `guides/03-gateway-intents.md`.
3. **Pin SDK major versions in package manifests.** discord.js and discord.py introduce breaking changes. Unpinned installs silently break bots in CI.
4. **Surface bot-verification at 75 servers, not 100.** The verification application takes 1-5 business days; missing the gate hard-blocks new guild joins. See `guides/06-verification-checklist.md`.
5. **Register commands to a test guild during development.** Global registration has ~1 hour propagation delay; guild-scoped is instant. See `guides/02-slash-commands.md`.
6. **Do not recommend Wavelink.** It is abandoned. Use Mafic/lavalink.py (Python) or Shoukaku/Lavalink-Client (Node.js). See `guides/04-voice-pipeline.md`.
7. **All new voice code must use DAVE-compliant clients.** The DAVE E2EE protocol is mandatory in all voice channels since March 1, 2026.

---

## Guide index

| Guide | When to use |
|-------|-------------|
| `guides/00-principles.md` | Architecture decisions: gateway vs HTTP, intent scoping, token hygiene |
| `guides/01-sdk-selection.md` | Choosing between discord.js, discord.py, Serenity, and forks |
| `guides/02-slash-commands.md` | Authoring slash, user-context, message-context commands; DeferReply pattern |
| `guides/03-gateway-intents.md` | Minimum-intent discipline, privileged intents, partial intents |
| `guides/04-voice-pipeline.md` | Lavalink 4 setup, DAVE-compliant clients, queue + event model |
| `guides/05-scaling-ops.md` | Sharding, REST-only mode, rate-limit handling, container health checks |
| `guides/06-verification-checklist.md` | Bot verification step-by-step (75-server trigger, 100-server hard block) |
| `guides/07-components-modals.md` | Buttons, select menus, modals, custom_id namespacing, ephemeral flows |

---

## Template index

| Template | Purpose |
|----------|---------|
| `templates/slash-command-discord-js.ts` | Minimal idiomatic slash command for discord.js v14 |
| `templates/slash-command-discord-py.py` | Minimal idiomatic slash command using discord.py app_commands |
| `templates/voice-queue-discord-js.ts` | Lavalink 4 + Shoukaku queue stub for discord.js |
| `templates/bot-verification-checklist.md` | Fillable checklist for the 100-server verification process |
| `templates/audit-report.md` | Skeleton for a full bot audit report |

---

## Example index

| Example | Demonstrates |
|---------|-------------|
| `examples/happy-path-slash-command.md` | End-to-end: register command, handle interaction, DeferReply |
| `examples/edge-case-modal-timeout.md` | Modal flow with orphaned-interaction handling |

---

## Open questions (flagged by scripture-historian)

> **TODO: stinger-forge open questions; resolve before next refresh:**

1. **Serenity/Poise (Rust)**: API surface not fully covered in research. Guides reference Rust conceptually; confirm `poise` slash command macro syntax from `docs.rs/poise` before next refresh.
2. **DisTube DAVE support**: Not confirmed. `guides/04-voice-pipeline.md` omits DisTube from active recommendations until DAVE compatibility is verified at `github.com/skick1234/DisTube`.
3. **Lavalink 4 Docker Compose YAML**: Reference snippet not retrieved. `guides/04-voice-pipeline.md` provides the install URL; embed the snippet on next refresh.
4. **discord.js REST rate-limit knobs**: Specific `RESTOptions` fields not retrieved. `guides/05-scaling-ops.md` covers the pattern; add specific field names on next refresh.
5. **Pycord vs discord.py**: Pycord is a maintained fork with growing adoption. `guides/01-sdk-selection.md` acknowledges the fork; defaults remain the Rapptz main-line unless the user specifies Pycord.

---

## Refresh cadence

- **Trigger immediately**: discord.js v15 reaches stable; Wavelink resumes maintenance (check `github.com/PythonistaGuild/Wavelink`); Discord announces API v11.
- **Annual review**: Full `normal`-depth scripture-historian re-run.
- **Quarterly**: Skim `discord.com/developers/docs/change-log` for breaking changes.

---

*Forged by stinger-forge from `ai-tools/command-briefs/discord-bot-wasp-drone-command-brief.md` + `research/research-summary.md`. Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*