Moderation: Commands, Warnings, Escalation and Mod Log

Kage's moderation consists of slash commands in the /mod group. They always work, even if you have set nothing up in the dashboard. In the dashboard you only decide whether and where the actions are additionally logged (mod log), and whether Kage automatically imposes a penalty at a certain number of warnings.

Every action is also stored as a case. That builds a history per member, which you retrieve with /mod history. For a short walkthrough, see the guides Setting up moderation and Mod log.

Requirements

• Moderators' permissions: Every command checks the permission it needs (see the table). By default the /mod group is only visible to members with the Kick Members permission. You can adjust this in Discord under *Server Settings → Integrations*.
• Kage's permissions: Kage needs the same permissions (Kick, Ban, Timeout Members, Manage Messages, Manage Channels). They are part of the standard invite.
• Role order: Kage's role must be above the members you want to punish in the role list.
• For the mod log: Kage needs Send Messages and Embed Links in the log channel.

The commands

Only you see the replies (ephemeral), except for lock and unlock: there, Kage replies visibly in the channel. If you give no reason, Kage shows the placeholder "No reason given" in replies and the mod log.

Important notes on roles and permissions

• Before kick, ban, softban and timeout, Kage checks whether its own highest role is above the target's highest role. If not, it refuses the action with a notice. Kage does not compare the executing person's role with the target's.
• /mod purge additionally needs Read Message History for Kage in the channel. If it is missing, Kage reports it instead of failing silently.
• lock sets "Send Messages" to *denied* for @everyone. unlock sets it back to *neutral*, not to *allowed*. Roles with their own overrides in the channel are unaffected.

Cases and history

Every action creates a case with number, type, moderator, reason and time:

Cases are immutable. You remove a wrong entry with /mod case-remove and the case number from /mod history; you cannot edit it. Internal notes work the same way: add, show, remove. All actions also appear in the module's Logs tab.

Automatic escalation

With escalation rules, Kage automatically follows up with a penalty at a certain number of warnings.

1. In the dashboard you create up to 10 rules: *At [number] warnings:* Timeout, Kick or Ban. For timeout you give the minutes (1 to 40,320, default 60).
2. Only one rule per warning count is allowed.
3. After each /mod warn, Kage counts the member's warnings (warnings only, not kicks or bans). If the count matches a rule exactly, Kage carries out the action.
4. Because the number has to match exactly, a further warning does not trigger the rule again. If you remove cases and the member reaches the number again later, the rule applies again.
5. Kage only carries out the action if it has the required permission and its role is above the member. Otherwise nothing happens, and no message appears in Discord.
6. The action appears in the mod log, with Kage as the moderator.

Escalation is triggered only by /mod warn. The rules apply independently of the "Log moderation actions" switch; that switch only controls the mod log.

The mod log

In the dashboard under Moderation you turn on Log moderation actions and choose a Log channel. A private channel that only the mod team sees is recommended. Kage then posts an embed with member, moderator and reason for these actions:

• Kick, ban, softban, timeout, warning
• Purge (with count and channel), channel lock, channel unlock
• Automatic escalations

Unbans, removed timeouts, removed cases and notes do not appear in the mod log. They are in the history and in the Logs tab, though. The mod log is separate from the audit log, which records general server activity.

Settings at a glance

Checking the result

1. Test a command: Run /mod warn on a test account. The reply names the case number and the total number of warnings.
2. History: /mod history shows the entry with number, type, date and moderator.
3. Mod log: The embed appears in the log channel.
4. Escalation: Warn a test account until the count matches a rule.

Troubleshooting

The /mod commands are not visible

You need at least the Kick Members permission to see the group. Check under *Server Settings → Integrations* whether the command is restricted for your role.

Kage refuses a kick, ban or timeout

Usually the member's role is above or level with Kage's role. Move Kage's role up in the role list. Also check that Kage has the required permission. Administrators and the server owner can never be put in timeout.

/mod purge reports missing permissions

Kage needs Manage Messages and Read Message History in the channel. The command also only works in text channels.

Nothing appears in the mod log

Check that "Log moderation actions" is on and a log channel is chosen and saved. Check Kage's permissions in the channel. Unbans and removed timeouts are never posted there.

Escalation does not trigger

The warning count must match a rule exactly. Only warnings (/mod warn) are counted, not kicks or bans. Also check Kage's permissions and role. Removed cases lower the count.

A case cannot be edited

Cases are immutable. Remove it with /mod case-remove and add a new one if needed.

Further reading

General server activity is recorded by the audit log. Regular cleanup is handled by Auto Purge. Automatic measures against spam and raids are described in Anti-spam and Anti-raid.