> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fs.soquincy.qzz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Moderation: Warn, Kick, Ban, Timeout, and Purge

> Use Freesona's moderation commands to warn, kick, ban, timeout, and purge — with configurable auto-threshold actions for warnings.

Freesona includes a full moderation suite with per-guild warning history, configurable auto-punishment thresholds, and all standard member and channel actions. Warning records are stored persistently in `warnings.db` — they survive restarts and redeployments.

The warning system lives in the `warns` module and core moderation actions live in the `moderation` module. Enable both before use:

```text theme={null}
/module enable moderation
/module enable warns
```

<Note>
  All moderation commands use the `~` prefix by default. Change your server's prefix with `~prefix <symbol>`. The new prefix is saved to `config.json` and persists across restarts.
</Note>

## Warning System

Issue, view, and manage per-guild warnings for any member:

| Command                       | Description                                                                                                           | Permission       |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `~warn <member\|id> [reason]` | Issue a warning with a unique hex ID. DMs the member with the reason and triggers any matching auto-threshold action. | Moderate Members |
| `~warns <member\|id>`         | Show all warnings for a member, including hex IDs, timestamps, and reasons.                                           | Moderate Members |
| `~delwarn <warn_id>`          | Delete a specific warning by its hex ID.                                                                              | Moderate Members |
| `~clearwarns <member\|id>`    | Clear all warnings for a member.                                                                                      | Moderate Members |

## Auto-Threshold Actions

Configure automatic punishments that trigger when a member reaches a set warning count:

* `~warnthresholds` (alias `~wt`, also `/warnthresholds`) — open the threshold editor modal
* Set one or more threshold rules per guild. Each rule maps a warning count to an action.

**Supported actions:**

| Action  | Format                                   |
| ------- | ---------------------------------------- |
| Timeout | `timeout <duration>` — e.g. `timeout 1h` |
| Kick    | `kick`                                   |
| Ban     | `ban`                                    |

**Example thresholds:**

* At **3 warnings** → `timeout 1h`
* At **5 warnings** → `kick`
* At **7 warnings** → `ban`

Thresholds are per-guild and saved to `config.json`. Use the slash command form `/warnthresholds` to open the modal directly.

## Member Actions

| Command                                        | Permission       |
| ---------------------------------------------- | ---------------- |
| `~kick <member> [reason]`                      | Kick Members     |
| `~ban <user> [delete_messages] [reason]`       | Ban Members      |
| `~softban <member> [delete_messages] [reason]` | Ban Members      |
| `~unban <user> [reason]`                       | Ban Members      |
| `~timeout <member> <duration> [reason]`        | Moderate Members |
| `~removetimeout <member>`                      | Moderate Members |

**Softban** bans and immediately unbans a member, which clears their recent message history without keeping them out of the server permanently. The default message deletion window is 7 days; pass a different value with `delete_messages` (e.g. `7d`).

**Timeout duration format:** `10m`, `1h`, `1d` — plain numbers with a unit suffix.

**Ban `delete_messages`:** Pass a duration like `7d` to delete that many days of message history on ban.

`~removetimeout` has aliases `~rt` and `~rto`. `~timeout` has alias `~to`.

## Channel Management

| Command                     | Permission      |
| --------------------------- | --------------- |
| `~purge <limit>`            | Manage Messages |
| `~slowmode <duration\|off>` | Manage Channels |
| `~lock [reason]`            | Manage Channels |
| `~unlock [reason]`          | Manage Channels |

`~purge` accepts a limit between 1 and 1000 messages. `~slowmode` takes the same duration format as `~timeout` (e.g. `30s`, `1m`) or `off` to disable. `~lock` and `~unlock` control `@everyone` send permissions on the current channel.

## Bot Whitelist

By default, Freesona ignores messages from other bots to prevent feedback loops. Use the whitelist to let specific bots through the message filter:

| Command                         | Permission    |
| ------------------------------- | ------------- |
| `/botwhitelist`                 | Administrator |
| `/botwhitelist add <bot_id>`    | Administrator |
| `/botwhitelist remove <bot_id>` | Administrator |

Pass the integer snowflake ID of the bot you want to allow. `/botwhitelist` with no arguments shows the current list of whitelisted bot IDs.