docs(design): define Leaf user stories

design/user-stories/us-001-opt-into-leaf-protection.md

@@ -0,0 +1,28 @@
+---
+type: User Story
+title: "US-001: Opt into Leaf protection"
+description: Let players voluntarily receive and relinquish a persistent Resistance boost.
+status: backlog
+---
+
+# US-001: Opt into Leaf protection
+
+As a **player**, I want to opt into Leaf protection so that I can receive a modest defensive boost while playing on a hard server.
+
+## Acceptance criteria
+
+- [ ] Players with the `leaf.use` permission, granted by default, can use `/leaf on`, `/leaf off`, and `/leaf status`.
+- [ ] `/leaf on` records the player's opt-in choice and grants Resistance I while Leaf is globally enabled.
+- [ ] Resistance remains continuously effective without distracting expiry or renewal messages or particles.
+- [ ] `/leaf off` records the player's opt-out choice and immediately removes only the Resistance effect managed by Leaf.
+- [ ] `/leaf status` clearly distinguishes the player's saved choice, active protection, administrative lock, and global Leaf state.
+- [ ] Repeating an already-satisfied `on` or `off` command is safe and explains that no change was needed.
+- [ ] Opt-in choices are keyed by UUID and survive logout and server restart.
+- [ ] A player who joins while opted in regains protection when Leaf is enabled.
+- [ ] Player-command autocomplete suggests only valid next arguments available to the sender.
+
+## Related
+
+- [US-002: Relinquish protection when attacking](us-002-relinquish-protection-when-attacking.md)
+- [US-003: Identify protected players](us-003-identify-protected-players.md)
+- [US-005: Administer Leaf](us-005-administer-leaf.md)