docs: add a PvP spell cooldowns section

guides/PvP/hits-and-defeat.md

@@ -1,6 +1,6 @@
 ---
 title: Hits and defeat
-description: How a spell hit between players lands, what the server checks, how much it costs, how to change hits with a policy, and what losing a fight does.
+description: How a spell hit between players lands, what the server checks, how much it costs, how to change hits with a policy, what losing a fight does, and how spell cooldowns work in a fight.
 sidebar:
   order: 475
 ---
@@ -77,6 +77,35 @@ On the client, `localDowned` fires as the local player kneels and `localDownedEn
 
 Players get their health back by themselves, and every PvP hit pauses that for 10 seconds. `player.setHealthRecovery(false)` stops it until you set it back to `true`. A respawn or any trip to another map turns recovery back on, so set it again afterwards.
 
+## Spell cooldowns
+
+Out of combat, the game recharges most spells in about a third of a second. Fighting enemies, it waits each spell's full cooldown. To the game, a fight between players is never combat, so HogwartsMP decides when a player is in a PvP fight:
+
+- a player hostile to them is within 50 m, or
+- they hit, or were hit by, a hostile player in the last `flagCombatLockSeconds`.
+
+While a player is in a PvP fight, every spell they cast waits its full cooldown, as it would against enemies. A cooldown that started in a fight keeps its full length after the fight ends.
+
+| Spell | In a PvP fight | Outside a fight |
+| --- | --- | --- |
+| Flipendo | 5 s | 0.33 s |
+| Accio, Incendio, Levioso | 8 s | 0.33 s |
+| Confringo, Depulso, Descendo, Expelliarmus, Glacius | 10 s | 0.33 s |
+| Arresto Momentum, Diffindo, Expulso | 15 s | 0.33 s |
+| Crucio | 20 s | 0.33 s |
+| Avada Kedavra | 90 s | 90 s |
+
+These are the game's base times, before any talent that shortens them. Stupefy, the basic cast, and Protego have no cooldown in the game at all, so nothing here limits them.
+
+The `cooldowns` rule turns this off. `"full"`, the default, works as above; `"fast"` keeps the out-of-combat recharge in fights too, for quick, spell-heavy PvP:
+
+```js
+// server/main.js
+Pvp.configure({ cooldowns: "fast" });
+```
+
+Each player's own game runs their cooldowns, so a changed game can ignore them. What the server limits is hits: 12 a second from any one attacker.
+
 ## Where to go next
 
 - [Rules and relations](/guides/pvp/rules-and-relations/) for who may fight whom.

guides/PvP/rules-and-relations.md

@@ -22,9 +22,10 @@ Out of the box nobody can hurt anybody. PvP starts when a script sets rules or p
 | `defeat` | `"death"` | What losing does: the game's own `"death"`, or a `"kneel"` that the player gets up from |
 | `curses` | `"on"` | `"off"` stops the Killing, Cruciatus and Imperius curses doing anything to players |
 | `kneelHp` | 1 | The health at which a kneel defeat starts, and the health a kneeling player is held at |
-| `flagCombatLockSeconds` | 15 | How long after a hit, given or taken, a player who drops their flag stays flagged |
+| `flagCombatLockSeconds` | 15 | How long after a hit, given or taken, a player who drops their flag stays flagged, and stays in a fight for [spell cooldowns](/guides/pvp/hits-and-defeat/#spell-cooldowns) |
 | `spawnProtectionSeconds` | 5 | How long a player killed in PvP cannot be hurt once they are back up; their own hit ends it |
 | `damageScale` | 1 | Multiplies every spell's [damage](/guides/pvp/hits-and-defeat/#damage) |
+| `cooldowns` | `"full"` | `"full"` gives spells their whole [cooldown](/guides/pvp/hits-and-defeat/#spell-cooldowns) in a PvP fight; `"fast"` keeps the game's out-of-combat recharge |
 
 ```js
 // server/main.js