Day-to-day moderation

Every moderation action has two paths: you can ask the bot in plain English, or you can run the matching slash command. Both routes hit the same tool layer, both enforce the same permission checks, and both open a confirmation thread for destructive actions. Use whichever is faster for the situation. Natural language is great when you are on mobile or you do not remember the exact option names. Slash is faster when you already know what you want.

Say someone is dropping spam links in a public channel. You want them muted for an hour while you cool the room down.

1. Identify the user. Right-click their name in Discord and copy their user ID, or have their mention handy.
2. Ask in plain English by mentioning the bot and describing what you want:

   @GameServerBot please timeout user 123456789 for 1 hour, spamming links

   The bot parses the request, picks the /mod timeout tool, and opens a confirmation thread under the channel you posted in.
3. Or run the slash command directly:

   /mod timeout user:@User minutes:60 reason:"spamming links"

   Same confirmation thread, same result.
4. Confirm in the thread. The bot posts the proposed action with Confirm and Cancel buttons. Click Confirm. The timeout lands; the reason is recorded; the user shows up in their own mod history with a timestamp.

The other actions in the suite work the same way. Each opens a confirmation thread before anything destructive happens:

• /mod kick user:@User reason:"why" removes the user from the guild. They can rejoin with a new invite.
• /mod ban user:@User reason:"why" removes them and blocks rejoins until you unban.
• /mod unban user_id:123456789 reason:"appeal accepted" reverses a ban. You need the user ID because banned users are not in the member picker.

All four (timeout, kick, ban, unban) require the matching Discord permission on your account. The bot also needs the matching permission. If either of you is missing it, the tool returns a clear error instead of trying.

The confirmation thread is the safety rail between "you asked for an action" and "the action happens." Anything destructive (timeout, kick, ban, unban, purge, flag-violation) routes through it. Read this once so the shape is familiar; you will see it dozens of times a week.

1. The bot opens a thread under the channel where you asked for the action. The thread is named after the action and the target user so other mods scanning the channel can tell what is going on at a glance.
2. The bot posts the proposed action in the thread: the tool name, the target, the reason, and the parameters it parsed from your request. Two buttons sit underneath: Confirm and Cancel.
3. Click Confirm and the bot executes the tool and posts the outcome in the same thread. Click Cancel and nothing happens; the thread closes itself.
4. Modify the parameters mid-flight by replying in the thread with a correction. For example, "actually make it 30 minutes, not 60." The bot re-opens the confirmation form with the updated values and posts a fresh pair of buttons. This is how you handle "wait, wrong user" or "make the reason more specific" without cancelling and starting over.
5. Walk away. If neither button is clicked, the thread auto-archives after a short timeout and the pending action expires. The bot will not silently apply something you forgot about.

Threads are visible to everyone in the parent channel who has thread-read permission, so other mods can see what you proposed even if they cannot click the button. That is intentional. Moderation should be auditable in real time.

Warnings are the soft layer of moderation. They do not affect the user's account, they do not get a DM, they do not show up in any public channel. They are an internal record that you and other mods can pull up later when deciding what to do next. Use them for offenses that are not bad enough for a timeout but you want on the books.

1. Record a warn:

   /mod warn user:@User reason:"backseat moderating in #general"

   The bot stores the warn with a timestamp, the mod who issued it (you), and the reason. Nothing else happens.
2. Attach a specific offending message with the optional message_id option. Right-click the message in Discord and copy its ID, then pass it in:

   /mod warn user:@User reason:"this exact post" message_id:1234567890

   The warn record links to the message so you have receipts if the user appeals later.
3. Warnings are invisible to the user being warned. No DM is sent. No public post is made. The only way the target finds out is if a mod tells them or if auto-escalation eventually triggers an action that is visible (timeout, kick, ban).
4. Other mods can see warns via the history command (covered later in this stage). That is how the warning system stays useful across a mod team. The user you warned at 2am is visible to the mod who is on at noon the next day.

Warns are also the input that drives auto-escalation. If you have escalation enabled, the Nth warn within a rolling window automatically triggers a timeout, ban, or whatever you configured. That is the next sub-section.

Auto-escalation lets you define a fixed ladder of consequences for repeat warnings. Instead of remembering "did I warn this person already this month?" and making a judgement call, the bot consults the ladder you set up once and applies the right action automatically. Useful for guilds big enough that no single mod sees every incident.

1. Turn on the policy:

   /mod escalate enable

   The bot starts counting warns against the ladder. With no rungs configured, the ladder is empty and nothing happens; you have to add rungs next.
2. Add rungs. Each rung is a (count, action, duration) triple. Walk up the ladder one step at a time:

   /mod escalate-rung add count:2 action:timeout duration:60

   /mod escalate-rung add count:3 action:timeout duration:1440

   /mod escalate-rung add count:4 action:ban

   Now: 1 warn does nothing (no rung at count 1, by design); 2 warns trigger a 1-hour timeout; 3 warns trigger a 24-hour timeout; 4 warns ban the user. The action and duration are applied automatically when a mod records the Nth warn.
3. Inspect the current ladder:

   /mod escalate show

   The bot prints every configured rung in order, the count threshold, the action, and the duration. Quick way to remember what you set up six months ago.
4. Adjust the ladder by removing a rung you no longer want or adding new ones. Rungs are independent records; changing one does not affect the others.

The point of escalation is consistency. Every user who reaches three warns gets the same response, regardless of which mod was on duty when they tripped the threshold. That is the contract you are signing up for when you enable it.

Before you decide whether to warn, timeout, or ban, you usually want to know what has already happened to this user. The history command pulls every recorded action against them, with timestamps and reasons, so you can see the pattern at a glance.

1. Pull the history:

   /mod history user:@User

   The bot replies with a list, newest first.
2. Read the entries. Each row shows the action type (warn, timeout, kick, ban, unban), the timestamp, the moderator who issued it, and the reason. Timeouts also show duration. Bans show whether they have been reversed.
3. Use it to inform your next move. Three warns in the last week is a very different situation from three warns spread across two years. Two timeouts followed by clean behavior for six months suggests the user has cooled off; a fourth incident inside a month suggests they have not.
4. Cross-reference with escalation. If you have auto-escalation enabled, the history view is also how you predict what the next warn will do. Two existing warns plus a fresh one is the rung that triggers a timeout (in the ladder above). No surprises.

History is the audit trail for the entire mod team. Anything any mod has done against this user, you can see. That is on purpose. Quiet bans that nobody else can pull up are a bad pattern.

Sometimes you do not need to action a user; you just need to delete the mess they made. Purge is the bulk-message-delete tool. It is the fastest way to clean a raid, a spam dump, or an off-topic thread that got out of hand.

1. Delete the last N messages in the current channel:

   /mod purge count:50

   The bot opens a confirmation thread, you click Confirm, and the most recent 50 messages in the channel disappear. The thread reports how many were actually deleted (Discord's bulk-delete API has limits, so the number can come back lower than you asked).
2. Scope the purge to one user with the optional user filter. Useful for cleaning up a single spammer without nuking the bystanders' conversation:

   /mod purge count:50 user:@Spammer

   The bot scans the last 50 messages and deletes only the ones from that user. If they posted 12 of those 50 messages, you delete 12 and leave the other 38 alone.
3. Mind the 14-day cap. Discord's bulk-delete API only works on messages less than 14 days old. Older messages cannot be cleared this way; they have to be deleted one at a time, which is not a job for purge.
4. Double-check the channel you are in before you confirm. Purge deletes from this channel, the one you ran the command in, not from wherever the offender was active.

Purge does not record an entry in the user's mod history (it is a channel-level action, not a user-level action). If you want a paper trail tied to a specific user, follow up with a /mod warn after the purge so the incident is on the books.

The flag-violation tool is the zero-tolerance escalation path. It is not for routine moderation. It is for content that goes beyond your guild's policy and into territory where the bot owner needs to know: real-world threats, exploitation imagery, doxxing, anything where the right answer is "remove this immediately and tell someone outside this guild." Use it sparingly. It is louder than every other tool in this stage.

1. Run the flag:

   /mod flag-violation user:@User reason:"posted CSAM in #general, message attached" message_id:1234567890

   The bot records the violation in a dedicated log that the bot owner sees, separate from your guild's mod history. The content (truncated) and the reason are stored with a 90-day TTL.
2. The user's AI access is revoked automatically. They can still use slash commands, but the natural-language agent will no longer respond to them anywhere the bot is installed. This is a global block, not a per-guild block.
3. The bot owner gets notified. Depending on how the bot is configured, the violation lands in a dedicated admin channel or on a private flag log. You do not need to do any out-of-band reporting yourself; the tool handles delivery.
4. Follow up with your own guild's action. Flag-violation does not ban the user from your guild. That is still your call. Typically you run a /mod ban immediately after flagging.

This tool exists because some content is bad enough that a per-guild mod response is not the full answer. The bot owner needs visibility so the user can be blocked from causing the same harm in other guilds running the same bot. If the content is "just" rule-breaking for your community, do not use this; use warn, timeout, or ban.