init

docs/03_Commands.md

@@ -0,0 +1,71 @@
+# Commands
+
+All commands require the caller to be in one of the `staff_groups` from config. Player-only (no console support yet).
+
+## Punishments
+
+### /ban <player> <reason>
+
+Permanent ban. Active across all servers in the network within a few hundred ms. Online target is disconnected immediately with the reason.
+
+### /tempban <player> <duration> <reason>
+
+Time-limited ban. Duration syntax: `30s`, `5m`, `2h`, `7d`, `1w`. Expires automatically (the active-ban query filters by `expires_at`).
+
+### /mute <player> <reason>
+
+Permanent mute. Cancels `PlayerChatEvent` for the target on every server. Loaded into a per-server in-memory cache on the target's connect so chat enforcement doesn't hit MySQL on every message.
+
+### /tempmute <player> <duration> <reason>
+
+Time-limited mute. Same duration syntax as tempban.
+
+### /kick <player> <reason>
+
+One-shot disconnect. Recorded in history but doesn't persist beyond that (the target can rejoin immediately).
+
+### /warn <player> <reason>
+
+Recorded in history and shown to the target as a message if they're online. No connection or chat impact.
+
+### /unban <player>
+
+Revokes any active ban or tempban for the player. Marks the punishment row as `active=0`, fills `revoked_at` / `revoked_by_*`. Original row stays in history.
+
+### /unmute <player>
+
+Same as unban but for mutes. Also clears the entry from the mute cache on any server where the player is online.
+
+## Staff chat
+
+### /sc <message>
+
+Broadcasts on the cross-server staff chat channel. Visible only to other players whose `getGroupsForUser` overlaps with `staff_groups`.
+
+System events (a ban being issued, an unban) also post a line on this channel automatically.
+
+## Lookup
+
+### /lookup <player>
+
+Shows:
+- Player's last-known name and UUID
+- Online status (and which server they're on, if any)
+- First-seen and last-seen timestamps
+- Any active ban
+- Any active mute
+
+If the player has never connected, only the name/UUID lookup happens via online players and may return nothing.
+
+### /history <player>
+
+Last 20 punishment entries for the player, most recent first. Each entry shows id, state (`ACTIVE` / `EXPIRED` / `REVOKED`), type, who issued it, when, and the reason.
+
+## Common error cases
+
+| Error message | Cause |
+|---|---|
+| "You do not have permission to use this command." | Caller isn't in any of `staff_groups`. |
+| "No player found with that name (online or in history)." | Name doesn't match any online player or any name in `staff_players_seen`. |
+| "Database error: ..." | MySQL query failed. Check NetworkCore connection (`/networkcore status`). |
+| "Bad duration. Use 30s, 5m, 2h, 7d, 1w." | Duration string didn't parse. Last char must be `s`/`m`/`h`/`d`/`w`, prefix must be a positive integer. |