diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md
index 2864b25..8eaeab2 100644
--- a/docs/CHEATSHEET.md
+++ b/docs/CHEATSHEET.md
@@ -85,7 +85,8 @@ make logs             # Follow logs
 admins = ["*!~user@trusted.host", "ops!*@*.ops.net"]
 ```
 
-IRC operators are auto-detected via WHO. Hostmask patterns use fnmatch.
+IRC operators are auto-detected via WHO on connect and on user JOIN
+(debounced 2s to handle netsplit floods). Hostmask patterns use fnmatch.
 
 ## Channel Management (admin)
 
diff --git a/docs/USAGE.md b/docs/USAGE.md
index 2a6ff67..b9464d6 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -206,7 +206,7 @@ Default format is `"text"` (human-readable, same as before).
 Commands marked as `admin` require elevated permissions. Admin access is
 granted via:
 
-1. **IRC operator status** -- detected automatically via `WHO` on channel join
+1. **IRC operator status** -- detected automatically via `WHO`
 2. **Hostmask patterns** -- configured in `[bot] admins`, fnmatch-style
 
 ```toml
@@ -220,6 +220,20 @@ admins = [
 Empty by default -- only IRC operators get admin access unless patterns
 are configured.
 
+### Oper Detection
+
+IRC operators are detected via the `*` flag in `WHO` replies. Detection
+happens at two points:
+
+- **On connect** -- `WHO #channel` for each configured channel
+- **On user JOIN** -- debounced `WHO #channel` (2-second window)
+
+The debounce prevents flooding the server during netsplit recovery: many
+rapid JOINs produce a single `WHO` per channel. Note that the first
+command after joining may not yet have oper status -- the debounced WHO
+fires after a 2-second delay. Users who `QUIT` are removed from the oper
+set automatically.
+
 | Command | Description |
 |---------|-------------|
 | `!whoami` | Show your hostmask and admin status |