Discord Docs Restructure & Feature Update

Date: 2026-03-17 Status: Draft Scope: docs/developer-docs/docs/discord/

Problem

The Discord bot docs section has 25 pages that mix admin, developer, and feature content. Pages like commands-reference.md (439 lines) cover all 32 commands in one list. Feature pages expose algorithm internals when admins just need configuration guidance. Recent features (reaction thresholds, self-similarity detection, admin restrictions, configurable emojis, queue management) need documenting but adding them to existing pages would worsen the density problem.

Audiences: Community admins/CMs, developers/integrators. Everyday users are served by the separate user-guide repo.

Solution: Audience Lanes

Restructure the Discord section from 25 pages into 14 focused pages organized by audience, with a changelog for recent features.

New Page Structure

discord/
├── overview.md
├── admin-guide/
│   ├── quick-start.md
│   ├── commands-reference.md
│   ├── rewards-and-events.md
│   ├── drops-and-reactions.md
│   ├── anti-spam-and-quality.md
│   ├── permissions-and-security.md
│   ├── analytics-and-operations.md
│   └── troubleshooting.md
├── developer-reference/
│   ├── architecture.md
│   ├── database-schema.md
│   ├── quality-scoring-internals.md
│   └── extending-the-bot.md
└── changelog.md

Note: The current directory is admin-guides/ (plural). The new structure uses admin-guide/ (singular) — this is a new directory, not a rename.

Page Descriptions

overview.md

What the bot does, key capabilities, who it's for
Feature highlights table (trimmed from current, not exhaustive)
Links to admin guide and developer reference as entry points
Trim current 106-line overview to ~60 lines

admin-guide/quick-start.md

Consolidates: setup.md + quickstart-guide.md + admin-guides/getting-started.md

Setup to first reward in 10 minutes
Step 1: Add bot to server
Step 2: /setup connect with brand ID and security key
Step 3: /test all to verify
Step 4: First /drop or event creation
"What's running automatically" section (GM/GN, quality messages)
Links to deeper guides for next steps

admin-guide/commands-reference.md

Replaces: current admin-guides/commands-reference.md

Admin commands ONLY (16 commands): setup, config, drop, reward, reaction-drop, stats, audit, kpi, reports, segments, export, perk, test, watch, milestone, queue
Each command: description, key options, example usage
Quick reference table at top
User commands (balance, daily, streak, etc.) are in the user-guide, not here

admin-guide/rewards-and-events.md

Consolidates: admin-guides/events-rewards-guide.md + parts of admin-guides/configuration.md + features/streaks-milestones.md + features/role-rewards.md + features/achievements.md

Sections:

Creating events — /config events action:create, event types, reward amounts, cooldowns
Trigger types — keyword, min-length, reaction count, channel-based
Configurable emojis — NEW: emoji: option, comma-separated for random selection, "none" to reset
Channel events — NEW: min_characters default (20), min-length and min-words config
Milestones — creating, criteria types (message_count, reaction_count, voice_time, streak_length, total_rewards, reactions_received), auto-assignment
Streaks & achievements — streak mechanics, multipliers, achievement unlocks
Role rewards — purchasable roles, /buy-role
Cooldowns — per-event, per-message, daily charge limits
Smart Rewards — multiplier system
Third-party bot integration — supported bots (Atom, MEE6, UnbelievaBoat, etc.), how rewards trigger from third-party bot messages

admin-guide/drops-and-reactions.md

Consolidates: admin-guides/drops-and-events.md + features/boost-events.md

Sections:

Button drops — /drop command, custom labels, lifespan, max claims
Reaction drops — /reaction-drop, attaching to existing messages, emoji selection
Reaction thresholds — NEW: unique user counting (not total reactions), threshold tiers (3/5/7/10/15/20/25/50)
Auto-drops with /watch — /watch start/stop/list, channel monitoring, template events
Boost events — Nitro boost detection, server tier progression rewards
Sample drop programs — practical examples from sample-programs.md (drop-related examples only)

admin-guide/anti-spam-and-quality.md

NEW page. Consolidates: admin-guides/moderation.md + quality-related content from features/natural-participation.md

Written as configuration guidance, not algorithm documentation. Framing: "knobs you can turn."

Sections:

Overview — the bot automatically filters low-effort and spam content
Quality thresholds — qualifying-score, min-words, min-length explained as settings
Slop detection — what it catches (AI-generated text, formal language), max-slop-score config
Similarity detection — max-similarity config, what it means ("rejects messages too similar to recent ones")
Self-similarity — NEW: detects users paraphrasing their own messages, max_self_similarity falls back to max_similarity
Cross-channel copy detection — NEW: server-wide buffer catches copy-paste across channels
Formality detection — max-formality config
Recommended settings — table of suggested thresholds for different community types (casual, professional, mixed)

admin-guide/permissions-and-security.md

NEW page. Content from: admin-guides/configuration.md (admin-roles section) + PR #23 changes

Sections:

Permission tiers — table: Full Admin, Event Manager, Perk Manager, Viewer with what each can do
Setting up admin roles — /config admin-roles add/remove/list
Discord-native permissions — ADMINISTRATOR and MANAGE_GUILD auto-grant Full Admin
Command visibility — NEW: admin commands hidden from non-admins in Discord UI (default_member_permissions: "0")
Centralized permission gate — NEW: runtime check blocks unauthorized access even if command visibility is overridden
Security key — HMAC setup and rotation

admin-guide/analytics-and-operations.md

Consolidates: admin-guides/analytics.md + admin-guides/daily-operations.md

Sections:

Stats dashboard — /stats overview, period selection
Audit log — /audit for transaction history
KPI tracking — /kpi set/view
Queue management — NEW: /queue status/retry/unstick, when to use each, what "stuck" means
Reports — /reports schedule
Segments — /segments list
Exports — /export type:csv

admin-guide/troubleshooting.md

Consolidates: current troubleshooting.md + admin-guides/common-questions.md

Problem → symptoms → solution format
Common issues: bot not responding, rewards not distributing, events not triggering
Permission issues section updated for new admin restrictions

developer-reference/architecture.md

Extracts Discord-relevant content from: root docs/architecture.md (which remains for the broader project) + technical details from feature pages

Gateway relay: Discord.js client → HTTP forwarder → Cloudflare Worker
Durable Objects for WebSocket gateway
Event pipeline: message → quality scoring → slop detection → reward distribution
KV storage patterns
Cron jobs (activity poller, cleanup)

developer-reference/database-schema.md

Kept from current, updated with:

NEW: reactions_received columns in discord_user_stats (migration 008)
Any schema changes from recent features

developer-reference/quality-scoring-internals.md

NEW page. Moved from: features/natural-participation.md + algorithm details from feature pages

Quality scoring algorithm (0-100 breakdown: length, words, vocabulary, structure, engagement, resources)
Slop detection internals (formality score, hedging patterns, contraction analysis)
Similarity metrics (Jaccard similarity, channel buffers, buffer sizes, eviction)
Cross-channel detection (server buffer, computeCrossChannelSimilarity)
Self-similarity tracking (selfMaxSimilarity, selfSimilarCount)
Composite slop score formula (weights for each signal)

developer-reference/extending-the-bot.md

NEW page. Extracted from: admin-guides/advanced-features.md + patterns in codebase

Adding a new slash command (register-commands.js + handler + router)
Adding a new event type (gateway relay → event handler)
Third-party bot integration (bot-detector patterns)
Adding new milestone criteria types
Testing patterns (vitest, mocking KV/Supabase)

changelog.md

NEW page. Living document for recent changes.

Format:

## March 2026

### Reaction Threshold Awards (Mar 16)
Rewards now trigger based on unique reactor count...
See: [Rewards & Events](/discord/admin-guide/rewards-and-events#reaction-thresholds)

### Admin Command Restrictions (Mar 13)
Admin commands are now hidden from non-admin users...
See: [Permissions & Security](/discord/admin-guide/permissions-and-security)

Entries for all ~10 recent features, each 2-3 sentences with link to relevant docs page.

Content Migration Map

Current File	Destination
`overview.md`	`overview.md` (trimmed)
`setup.md`	`admin-guide/quick-start.md`
`quickstart-guide.md`	`admin-guide/quick-start.md`
`database-schema.md`	`developer-reference/database-schema.md`
`troubleshooting.md`	`admin-guide/troubleshooting.md`
`sample-programs.md` (367 lines)	Drop-related examples → `drops-and-reactions.md`; event config examples → `rewards-and-events.md`; remaining deprecated
`admin-guides/getting-started.md`	`admin-guide/quick-start.md`
`admin-guides/commands-reference.md`	`admin-guide/commands-reference.md` (admin only)
`admin-guides/configuration.md`	Split: `rewards-and-events.md` + `permissions-and-security.md`
`admin-guides/events-rewards-guide.md`	`admin-guide/rewards-and-events.md`
`admin-guides/drops-and-events.md`	`admin-guide/drops-and-reactions.md`
`admin-guides/analytics.md`	`admin-guide/analytics-and-operations.md`
`admin-guides/daily-operations.md`	`admin-guide/analytics-and-operations.md`
`admin-guides/moderation.md`	`admin-guide/anti-spam-and-quality.md`
`admin-guides/common-questions.md`	`admin-guide/troubleshooting.md`
`admin-guides/advanced-features.md`	Split: relevant admin pages + `developer-reference/extending-the-bot.md`
`features/account-linking.md`	`admin-guide/permissions-and-security.md` (account linking config section) + user-guide for user-facing steps
`features/achievements.md`	`admin-guide/rewards-and-events.md`
`features/boost-events.md`	`admin-guide/drops-and-reactions.md`
`features/gaming-integration.md`	`developer-reference/extending-the-bot.md` (marked as planned/unregistered feature)
`features/kpi-tracking.md`	`admin-guide/analytics-and-operations.md`
`features/natural-participation.md`	Split: `anti-spam-and-quality.md` (config) + `quality-scoring-internals.md` (algorithms)
`features/role-rewards.md`	`admin-guide/rewards-and-events.md`
`features/streaks-milestones.md`	`admin-guide/rewards-and-events.md`
`features/third-party-bots.md` (256 lines)	`admin-guide/rewards-and-events.md` (supported bots list, config) + `developer-reference/extending-the-bot.md` (integration patterns)

Commands NOT covered in admin commands-reference (documented in user-guide instead): join, daily, claim, balance, help, roles, buy-role, perks, perk-buy, streak, voice, leaderboard, link, milestones, cooldowns, notifications

Page Templates

Admin Guide Page Template

---
title: Page Title
description: One-line for SEO
sidebar_label: Short Label
sidebar_position: N
keywords: [relevant, keywords]
---

# Page Title

:::tip[TL;DR]
2-3 sentences: what this page covers and when you need it.
:::

## Quick Reference

| Setting/Command | What it does | Example |
|---|---|---|
| ... | ... | ... |

## Section Title

Task-oriented content. "How to do X."

### Subsection

Specific steps with real command examples.

Developer Reference Page Template

---
title: Page Title
description: Technical description
sidebar_label: Short Label
sidebar_position: N
---

# Page Title

> Technical reference for [system]. For configuration, see [Admin Guide link].

## Architecture Context

Where this fits in the system.

## How It Works

Technical details, data flow, algorithms.

## Code Examples

Relevant snippets.

// In sidebars.ts, the Discord section becomes:
{
  type: 'category',
  label: '🎮 Discord Bot',
  items: [
    'discord/overview',
    {
      type: 'category',
      label: 'Admin Guide',
      items: [
        'discord/admin-guide/quick-start',
        'discord/admin-guide/commands-reference',
        'discord/admin-guide/rewards-and-events',
        'discord/admin-guide/drops-and-reactions',
        'discord/admin-guide/anti-spam-and-quality',
        'discord/admin-guide/permissions-and-security',
        'discord/admin-guide/analytics-and-operations',
        'discord/admin-guide/troubleshooting',
      ],
    },
    {
      type: 'category',
      label: 'Developer Reference',
      collapsed: true,
      items: [
        'discord/developer-reference/architecture',
        'discord/developer-reference/database-schema',
        'discord/developer-reference/quality-scoring-internals',
        'discord/developer-reference/extending-the-bot',
      ],
    },
    'discord/changelog',
  ],
}

New Feature Documentation

Feature	Page	Section
Reaction threshold awards	`drops-and-reactions.md`	Reaction Thresholds
Self-similarity detection	`anti-spam-and-quality.md`	Self-Similarity
Cross-channel copy detection	`anti-spam-and-quality.md`	Cross-Channel Copy Detection
Admin command restrictions	`permissions-and-security.md`	Command Visibility + Centralized Gate
Configurable emojis	`rewards-and-events.md`	Configurable Emojis
Queue management	`analytics-and-operations.md`	Queue Management
Min-characters enforcement	`rewards-and-events.md`	Channel Events
Milestone criteria overhaul	`rewards-and-events.md`	Milestones
reactions_received columns	`database-schema.md`	Schema update
Restored notifyUser calls	`changelog.md`	Bug fix entry
Cross-wallet balance	`changelog.md`	Brief mention

Redirect Strategy

Old pages that move to new URLs need Docusaurus client-side redirects via the @docusaurus/plugin-client-redirects plugin (if installed) or manual redirect entries. Key redirects:

Old URL	New URL
`/discord/setup`	`/discord/admin-guide/quick-start`
`/discord/quickstart-guide`	`/discord/admin-guide/quick-start`
`/discord/admin-guides/getting-started`	`/discord/admin-guide/quick-start`
`/discord/admin-guides/commands-reference`	`/discord/admin-guide/commands-reference`
`/discord/admin-guides/events-rewards-guide`	`/discord/admin-guide/rewards-and-events`
`/discord/admin-guides/drops-and-events`	`/discord/admin-guide/drops-and-reactions`
`/discord/admin-guides/analytics`	`/discord/admin-guide/analytics-and-operations`
`/discord/admin-guides/moderation`	`/discord/admin-guide/anti-spam-and-quality`
`/discord/features/*`	Various (see migration map)

If the redirect plugin is not installed, old files can be replaced with stub pages containing frontmatter redirects or meta refresh tags.

Verification

Build docs locally: cd docs/developer-docs && npm run build
Verify no broken internal links
Check sidebar renders correctly with new structure
Confirm old URLs redirect or return appropriate content (no silent 404s)
Review each page stays under ~300 lines (target for digestibility)
Verify user-facing commands are documented in user-guide, not in admin commands-reference

Problem​

Solution: Audience Lanes​

New Page Structure​

Page Descriptions​

overview.md​

admin-guide/quick-start.md​

admin-guide/commands-reference.md​

admin-guide/rewards-and-events.md​

admin-guide/drops-and-reactions.md​

admin-guide/anti-spam-and-quality.md​

admin-guide/permissions-and-security.md​

admin-guide/analytics-and-operations.md​

admin-guide/troubleshooting.md​

developer-reference/architecture.md​

developer-reference/database-schema.md​

developer-reference/quality-scoring-internals.md​

developer-reference/extending-the-bot.md​

changelog.md​

Content Migration Map​

Page Templates​

Admin Guide Page Template​

Developer Reference Page Template​

Sidebar Configuration​

New Feature Documentation​

Redirect Strategy​

Verification​

Problem

Solution: Audience Lanes

New Page Structure

Page Descriptions

overview.md

admin-guide/quick-start.md

admin-guide/commands-reference.md

admin-guide/rewards-and-events.md

admin-guide/drops-and-reactions.md

admin-guide/anti-spam-and-quality.md

admin-guide/permissions-and-security.md

admin-guide/analytics-and-operations.md

admin-guide/troubleshooting.md

developer-reference/architecture.md

developer-reference/database-schema.md

developer-reference/quality-scoring-internals.md

developer-reference/extending-the-bot.md

changelog.md

Content Migration Map

Page Templates

Admin Guide Page Template

Developer Reference Page Template

Sidebar Configuration

New Feature Documentation

Redirect Strategy

Verification