🌊 Kaira — Modern Discord Moderation

No-nonsense moderation, audit-grade logging, and setup diagnostics — all in one bot.

---

🎯 Why Kaira?

Most moderation bots either miss features or break silently when admins forget to drag the bot role up. Kaira solves both:

• 🏷️ Unique Case IDs (CASE-XXXX-XXXXXX) for every infraction — look up any action weeks later with /case
• ⏱️ Native Discord timeouts by default, with a mute-role fallback for punishments longer than 28 days
• 🔍 /diagnose — one command that checks every permission, role-hierarchy position, log channel, and configured roles, then tells admins exactly what to fix
• 🔒 Privacy-first: /privacy baked in, /resetdata wipes all server data on demand, and we never share data with third parties

---

🔨 Moderation Suite

Every mod action writes to both the infraction database and the mod log (if enabled).

Command	What it does
/warn @user reason:	Warn a member, DM them the reason, and log it
/mute @user duration:1h reason:	Native timeout (≤28d) or mute-role fallback — use use_role:True to force the role
/unmute @user	Remove timeout and/or mute role in one command
/kick @user reason:	Kick with reason and Case ID
/ban @user reason: delete_messages:0	Permanent ban (0-7 days of messages deleted)
/tempban @user duration:7d reason:	Temporary ban — Kaira auto-unbans on expiry
/unban @user reason:	Unban by ID or mention
/purge amount:50 from_user:	Bulk delete 1-100 messages (<14d old), optionally from a single user

All commands validate role hierarchy so staff can't ban admins, and the bot can't punish members above its top role.

---

📋 Infraction Tracking

• /warnings @user active_only:True — full history of warns, mutes, kicks, bans, timeouts, and purges for a member
• /case CASE-0001-ABC123 — deep-dive into any action (who did it, when, reason, duration, target, state)
• /modlogs limit:50 — recent moderation activity across the server

---

📜 6 Log Categories

Run /setlog channel:#logs once, then toggle each stream with /logtoggle type category:

Category	Events recorded
🟩 Message Logs	Deleted messages, edited messages
🟦 Member Logs	Joins, leaves, account-age on join
🟪 Mod Logs	Warns, mutes, kicks, bans, purges, unbans, unmutes
🟥 Ban/Kick Logs	Bans, unbans, and kicks (from Discord's audit log stream)
🟧 Role/Nick Logs	Role add/remove, nickname changes
🟨 Channel Logs	Channel creates, deletes

Ignore filters (toggle with /logtoggle ignore rule:):

• 🤖 Ignore Bots — skip bot activity
• 🚫 Ignore Log Channel — don't log what happens inside the log channel itself

---

👋 Welcome & Autorole

• /setwelcome channel:#welcome → configure join & leave messages in their own channel
• Placeholders: {user} {username} {tag} {userid} {server} {membercount}
• Preview templates with /setwelcome preview
• /setautorole role:@NewMember enabled:True → auto-assign a role to every new member
• Failures are isolated — one broken autorole won't block the join log or welcome message

---

⚙️ Settings Dashboard

/settings gives admins a single, color-coded view:

• Core toggles (autorole, mute-role, native-timeout default, bug reports)
• Each log category state
• Ignore rules
• Welcome/leave channel + preview of messages
• Footer links to every config command

---

🧪 Diagnostics (Your "It Won't Work?" Button)

We can't make admins drag the bot role up — but we can tell them exactly when and why it's broken.

Run /diagnose for a live report:

✅ Permissions check — 13 flags (9 critical, 4 optional) with per-feature explanations ✅ Role hierarchy — counts roles above/below the bot, flags unreachable members ✅ Settings sanity — log channel perms, welcome channel perms, autorole/mute-role relative position ✅ Action Items list — tells the admin exactly which settings page to open

Default ephemeral (only you see it); add public:True to share with the team.

---

🔒 Privacy & Control

• /privacy — full, always-up-to-date privacy policy & ToS right in Discord
• /resetdata — server admins wipe all Kaira-held data for their server at any time (Manage Server, irreversible)
• /bugreport title: description: — rate-limited user feedback channel (admins can disable in settings)
• We store: settings, infractions, timed-punishment expiry, and bug reports. Nothing more.

---

🛠️ Utility Commands

• /ping — bot latency & uptime
• /help — tabbed command reference (Utility / Moderation / Infractions / Config)
• /bugreport — send feedback or bug reports to the bot owner

---

🚀 Quick Start

After inviting Kaira, any admin can get fully set up in ~2 minutes:

1. Server Settings → Roles → drag the Kaira role near the top, above any roles it should manage or moderate
2. Run /diagnose public:True to confirm everything is green
3. /setlog channel:#logs and /logtoggle type category:ModLogs (repeat for each category you want)
4. Optional: /setwelcome channel:#welcome + /setautorole role:@Member
5. Done.

---

📌 Notes

• Slash commands are guild-only (no DM usage — avoids permission crashes)
• Punishments exceeding Node's timer limits are re-scheduled automatically
• If Kaira stops responding, just re-run /diagnose — 9 out of 10 times it's the bot role position 😉