feat(vigilante): add arena boss succession

design/user-stories/index.md

@@ -18,3 +18,4 @@
 16. [US-016: Manage Followers through the Vigilante control panel](us-016-manage-vigilante-control-panel.md)
 17. [US-017: Use bound role control items](us-017-use-bound-role-control-items.md)
 18. [US-018: Complete Tyrant commands contextually](us-018-complete-commands-contextually.md)
+19. [US-019: Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-001-start-pause-and-administer.md

@@ -12,15 +12,16 @@ As a **server operator**, I want to start, pause, resume, and inspect the game s
 ## Acceptance criteria
 
 - [x] An administrator can start the first game by assigning the initial Tyrant.
-- [x] The administrator may assign the first Vigilante or allow random selection from eligible recently active players.
+- [x] The administrator may assign the first Vigilante or leave the role vacant for the configured Vigilante arena challenge.
 - [x] An administrator can pause and resume the game without deleting game state.
 - [x] Pausing freezes progression, cooldowns, daily-use timers, inactivity checks, and pending-selection deadlines.
 - [x] Role and class effects are suppressed while paused and restored when play resumes.
 - [x] Administrative commands require the `spigottyrant.admin` permission, granted to server operators by default.
-- [x] Administrators can inspect lifecycle state, roles, classes, Followers, purchases, levels, cooldowns, participation, and pending selections.
+- [x] Administrators can inspect lifecycle state, roles, classes, Followers, purchases, levels, cooldowns, participation, pending selections, and the configured Vigilante arena location.
 - [x] Destructive administrative operations require explicit confirmation.
 
 ## Related
 
 - [Tyrant game state machine](../concepts/game-state-machine.md)
 - [Configure and persist game state](us-012-configure-and-persist-state.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-008-support-vigilante-and-followers.md

@@ -11,7 +11,7 @@ As the **Vigilante**, I want nearby living Followers to strengthen me against th
 
 ## Acceptance criteria
 
-- [x] Exactly one active Vigilante exists while the game is running whenever an eligible player is available.
+- [x] A running game has at most one active Vigilante; a vacancy remains open until an eligible player defeats the arena boss.
 - [x] The Vigilante can invite eligible opted-in players to become Followers, and recruitment requires acceptance.
 - [x] The Vigilante can dismiss Followers and Followers can leave voluntarily.
 - [x] While actively fighting the Tyrant, the Vigilante gains one potion level each of Strength and Resistance per living Follower in the same world within 50 blocks.
@@ -19,17 +19,18 @@ As the **Vigilante**, I want nearby living Followers to strengthen me against th
 - [x] A Vigilante or Follower may simultaneously hold one Tyrant-side class without losing Vigilante-side membership.
 - [x] Effect levels update promptly as combat starts or ends and as Followers move, die, respawn, disconnect, or change assignment.
 - [x] Scaling is capped by validated configuration, defaulting to Strength V and Resistance IV.
-- [x] Every Vigilante death ends the assignment and triggers random replacement regardless of cause.
-- [x] The deceased Vigilante is excluded when another eligible non-Tyrant candidate exists and is reused only when no such candidate exists.
+- [x] Every Vigilante death ends the assignment and opens the one-player arena challenge while a Tyrant is active.
+- [x] The deceased Vigilante may immediately compete again under the same arena eligibility and reset rules as every other participant.
 - [x] Followers are cleared rather than transferred when their Vigilante dies or loses the position.
 - [x] The Tyrant is never eligible to be selected as Vigilante.
 - [x] The Vigilante can review, invite, and dismiss Followers through the Vigilante control panel.
 - [x] Control-panel and command-based Follower actions enforce identical eligibility and membership rules.
 - [x] The control panel communicates the current nearby-Follower combat contribution and configured effect caps.
-- [x] Relinquishing through the control panel follows normal Vigilante succession and Follower cleanup.
+- [x] Relinquishing through the control panel clears Followers and opens the Vigilante arena challenge.
 
 ## Related
 
 - [Role and class model](../concepts/role-and-class-model.md)
 - [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
 - [Manage Followers through the Vigilante control panel](us-016-manage-vigilante-control-panel.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-010-handle-inactivity-and-selection.md

@@ -15,14 +15,15 @@ As a **participant**, I want inactive central roles to be replaced fairly so tha
 - [x] Random candidates are drawn from eligible opted-in players who logged in during the preceding 24 hours.
 - [x] The Tyrant is always excluded from Vigilante selection.
 - [x] A previous role holder is excluded when another eligible candidate exists and may be reused only as a fallback.
-- [x] Tyrant inactivity ends the reign, clears all assignments, and invokes normal random Tyrant succession followed by Vigilante selection.
-- [x] Vigilante inactivity clears Followers and rerolls only the Vigilante position.
+- [x] Tyrant inactivity ends the reign, clears all assignments, invokes normal random Tyrant succession, and opens the Vigilante arena challenge once a Tyrant is active.
+- [x] Vigilante inactivity clears Followers and opens the Vigilante arena challenge without changing the Tyrant.
 - [x] An offline randomly selected candidate must log in within 24 unpaused hours to confirm the assignment.
-- [x] An unconfirmed selection expires and rerolls automatically under the same eligibility rules.
-- [x] Selection remains vacant and retries periodically when no valid candidate exists.
+- [x] An unconfirmed Tyrant selection expires and rerolls automatically under the same eligibility rules.
+- [x] Tyrant selection remains vacant and retries periodically when no valid candidate exists.
 - [x] Candidate selection cannot assign conflicting roles or choose an opted-out player, including during concurrent joins and deaths.
 
 ## Related
 
 - [Tyrant game state machine](../concepts/game-state-machine.md)
 - [Inform players and manage participation](us-011-inform-and-manage-participation.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-011-inform-and-manage-participation.md

@@ -15,6 +15,7 @@ As a **player**, I want to understand my status and control my eligibility so th
 - [x] Eligible players are invited to opt out of Tyrant events without implying that an event is currently running.
 - [x] An unassigned opted-in player is told that they are eligible and shown the opt-out command.
 - [x] An opted-out player is told when they may opt back in.
+- [x] Opted-in players are told the Vigilante arena world and coordinates when its role opens and when they join during an open challenge; opted-out players receive no such notice.
 - [x] An unassigned player can opt out through a command.
 - [x] Opting out removes an ordinary class or Follower assignment immediately; the Tyrant and Vigilante must relinquish through a safe role command before opting out.
 - [x] Opted-out players cannot be randomly selected, recruited, or assigned a class.
@@ -35,3 +36,4 @@ As a **player**, I want to understand my status and control my eligibility so th
 
 - [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
 - [Persistence model](../concepts/persistence-model.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-012-configure-and-persist-state.md

@@ -11,10 +11,10 @@ As a **server operator**, I want configurable and durable game behavior so that
 
 ## Acceptance criteria
 
-- [x] Configuration covers ranges, durations, cooldowns, inactivity periods, candidate windows, retry intervals, effect levels and caps, mob restrictions, item materials and names, messages, and timer behavior.
+- [x] Configuration covers ranges, durations, cooldowns, inactivity periods, candidate windows, retry intervals, effect levels and caps, mob restrictions, item materials and names, messages, timer behavior, and Vigilante arena boss balance.
 - [x] Defaults match the approved user stories, including a 50-block Tyrant range and Follower range, seven-day opt-out, 48-hour inactivity, and 24-hour candidate windows.
 - [x] Invalid required configuration prevents partial plugin initialization and produces a clear server log message.
-- [x] UUID-keyed state stores lifecycle, current and pending roles, assignments, login history, participation, reign progression, purchases, choices, cooldowns, paused time, item delivery, and captured mobs.
+- [x] UUID-keyed state stores lifecycle, current and pending roles, assignments, login history, participation, reign progression, purchases, choices, cooldowns, paused time, item delivery, and captured mobs; the administrator-set arena center is durable across restarts.
 - [x] Cooldowns and deadlines use UTC instants and exclude administratively paused time.
 - [x] State is saved using atomic replacement where supported so failed writes do not replace valid state with partial data.
 - [x] Corrupt, unknown, or invalid records cannot silently grant progression, roles, powers, items, or duplicated mobs.
@@ -25,3 +25,4 @@ As a **server operator**, I want configurable and durable game behavior so that
 
 - [Persistence model](../concepts/persistence-model.md)
 - [Build, test, and release the plugin](us-013-build-test-and-release.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-016-manage-vigilante-control-panel.md

@@ -29,7 +29,7 @@ As the **Vigilante**, I want a control panel for managing Followers so that I ca
 - [x] The Follower-management screen identifies current Followers and requires confirmation before dismissal.
 - [x] Successful invitations and dismissals refresh the control panel from authoritative current state and notify affected players.
 - [x] The role-control screen allows the Vigilante to relinquish the role only after explicit confirmation.
-- [x] Relinquishing through the control panel uses normal Vigilante replacement and Follower-cleanup rules.
+- [x] Relinquishing through the control panel clears Followers, opens the Vigilante arena challenge, and communicates that outcome accurately.
 - [x] Every action revalidates the running lifecycle and active Vigilante before changing state.
 - [x] Stale or repeated control-panel interactions cannot invite an ineligible player, duplicate an invitation, or dismiss the wrong Follower.
 - [x] Existing `/vigilante invite`, `/vigilante accept`, `/vigilante dismiss`, `/vigilante leave`, and `/tyrant relinquish confirm` commands remain available.
@@ -46,3 +46,4 @@ Automated tests verify default and explicit command entry points, active-Vigilan
 - [Manage a reign through the Tyrant control panel](us-015-manage-tyrant-control-panel.md)
 - [Role and class model](../concepts/role-and-class-model.md)
 - [Use bound role control items](us-017-use-bound-role-control-items.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-018-complete-commands-contextually.md

@@ -21,6 +21,7 @@ As a **player or administrator**, I want contextual command suggestions so that
 - [x] `/tyrantadmin` suggestions are visible only to senders with `spigottyrant.admin`.
 - [x] `/tyrantadmin start` suggests online Tyrant and Vigilante candidates.
 - [x] `/tyrantadmin reset` suggests `confirm`.
+- [x] `/tyrantadmin arena` suggests `set` and `status`.
 - [x] Suggestions are filtered case-insensitively by the partially typed argument.
 - [x] Suggestions never include syntactically invalid options for the current argument position.
 - [x] Console completion works for administrative commands without exposing player-only commands as executable console actions.
@@ -36,4 +37,5 @@ Automated tests verify root syntax, unlocks, classes, confirmations, eligible re
 - [Assign unlocked classes](us-004-assign-unlocked-classes.md)
 - [Support the Vigilante and Followers](us-008-support-vigilante-and-followers.md)
 - [Manage a reign through the Tyrant control panel](us-015-manage-tyrant-control-panel.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)
 - [Manage Followers through the Vigilante control panel](us-016-manage-vigilante-control-panel.md)

design/user-stories/us-019-claim-vigilante-in-arena.md

@@ -0,0 +1,35 @@
+---
+type: User Story
+title: "US-019: Claim the Vigilante role in the arena"
+description: Let one eligible player at a time defeat a protected arena boss to claim a vacant Vigilante role.
+status: done
+---
+
+# US-019: Claim the Vigilante role in the arena
+
+As an **opted-in participant**, I want a visible one-player boss challenge for a vacant Vigilante role so that succession is earned through an open contest.
+
+## Acceptance criteria
+
+- [x] An administrator can set and inspect a durable arena center, and configuration validates the arena radius and boss strength.
+- [x] The configured arena has a continuously visible particle boundary, including when no fight is active.
+- [x] A vacant Vigilante role opens the challenge after death, inactivity, relinquishment, or a new Tyrant reign, but a boss exists only while a Tyrant is active and the game is running.
+- [x] The challenge boss defaults to an armored, 80-health enhanced zombie, does not burn in sunlight, and remains within a default 10-block-radius arena.
+- [x] All online opted-in players are told when the role opens and receive the arena world and coordinates; opted-in players receive the same notice when they log in while it remains open, and opted-out players do not.
+- [x] Exactly one eligible opted-in non-Tyrant player may enter as challenger, including when entry is attempted by walking or teleportation.
+- [x] Starting a fight replaces the passive particle boundary with temporary actual `BARRIER` blocks that are removed safely without permanently changing existing blocks.
+- [x] Any non-challenger who enters or respawns inside the arena is moved safely outside it.
+- [x] Existing mobs in the arena and mobs that spawn or enter it are removed while preserving the arena boss.
+- [x] The boss attacks only the active challenger, and only that challenger can damage the boss.
+- [x] Challenger death, disconnect, or leaving by any mechanism ends the fight and resets the boss to full health at its spawn; death counts as leaving and the same player may retry immediately.
+- [x] Killing the boss assigns the challenger as Vigilante, removes the boss and barriers, and restores the passive particle boundary.
+- [x] Pausing, resetting, restarting, reloading, and repeated or concurrent events cannot duplicate the boss, barriers, challenger, or Vigilante assignment.
+- [x] If the arena is not configured when a challenge should open, the Vigilante remains vacant and administrators receive a clear warning.
+
+## Related
+
+- [Start, pause, and administer the game](us-001-start-pause-and-administer.md)
+- [Support the Vigilante and Followers](us-008-support-vigilante-and-followers.md)
+- [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
+- [Configure and persist game state](us-012-configure-and-persist-state.md)
+- [Tyrant game state machine](../concepts/game-state-machine.md)