feat(pocket-base): unlock flight by completing raids

design/log.md

@@ -149,3 +149,10 @@ description: Chronological record of material decisions affecting the Spigot Bas
 - Cleared accumulated fall distance whenever portal or void-return travel teleports an entity, preventing carried-over fall damage at the destination.
 - Added regression coverage for players falling out of a Pocket Base and returning to the server spawn.
 - Verified the fix and plugin artifact with `./gradlew clean check jar`.
+
+## 2026-08-28 — Raid-earned Pocket Base flight
+
+- Made a successful raid victory by the owner inside their own Pocket Base permanently unlock owner-only Survival flight.
+- Limited Pocket Base flight to its expanding horizontal boundary plus a 16-block warning buffer while allowing the world's full build height.
+- Persisted unlocks with safe locked defaults for existing records and exposed progress through chat status and the native settings dialog.
+- Verified 140 tests and the Java 25 plugin artifact with `./gradlew clean check jar`.

design/user-stories/index.md

@@ -26,3 +26,4 @@ description: Catalog of user stories for the Spigot Base plugin.
 18. [US-018: Control Pocket Base mob spawning](us-018-control-pocket-base-mob-spawning.md)
 19. [US-019: Change a Pocket Base biome](us-019-change-a-pocket-base-biome.md)
 20. [US-020: Control a base through a dialog UI](us-020-control-base-through-dialog-ui.md)
+21. [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md)

design/user-stories/us-009-view-progression-and-notifications.md

@@ -12,6 +12,7 @@ As a **player**, I want to inspect my progression and receive timely milestone f
 ## Acceptance criteria
 
 - [x] `/basesettings status` shows the player's Base, Base Size, Base Flight, Teleport Warm-up, and Teleport Cooldown paths plus current visitor, navigation, flight, and boss-bar settings.
+- [x] `/basesettings status` shows whether Pocket Base flight still requires a successful owner raid or has been unlocked.
 - [x] Each path identifies earned levels, unmet prerequisites, current progress, the next threshold, and the next reward.
 - [x] Locked secondary paths clearly identify Base I or another sequential level as their prerequisite.
 - [x] Relevant qualifying activity briefly displays a configurable progress boss bar for the active milestone.
@@ -31,3 +32,4 @@ As a **player**, I want to inspect my progression and receive timely milestone f
 - [US-001: Unlock and establish Base I](us-001-unlock-and-establish-base.md)
 - [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md)
 - [US-010: Administer player progression](us-010-administer-player-progression.md)
+- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md)

design/user-stories/us-011-configure-and-persist-progression.md

@@ -17,6 +17,7 @@ As a **server operator**, I want progression behavior to be configurable and dur
 - [x] Radii, vertical ranges, durations, and prices reject unsafe or nonsensical values.
 - [x] Invalid required configuration prevents partial plugin initialization and produces a clear server log message.
 - [x] UUID-keyed state persists latest known names, base locations, counters, levels, relocation times, teleport times, visitor cooldowns, navigation preferences, flight preferences, boss-bar preferences, and visitor settings.
+- [x] UUID-keyed Pocket Base state persists raid-earned flight unlocks, with missing legacy values defaulting safely to locked.
 - [x] Cooldowns and relocation limits use real elapsed timestamps and continue while players are offline.
 - [x] State is saved safely so a failed write does not replace valid persisted state with a partial document.
 - [x] Corrupt, unknown, or invalid records are handled defensively and cannot silently grant progression or privileges.
@@ -28,3 +29,4 @@ As a **server operator**, I want progression behavior to be configurable and dur
 - [US-003: Expand the base](us-003-expand-the-base.md)
 - [US-010: Administer player progression](us-010-administer-player-progression.md)
 - [US-012: Build and release the plugin](us-012-build-and-release-plugin.md)
+- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md)

design/user-stories/us-020-control-base-through-dialog-ui.md

@@ -16,6 +16,7 @@ As a **player**, I want a dialog-based base dashboard so that I can inspect prog
 - [x] `/basesettings status` retains the chat-based progression report.
 - [x] The dialog summarizes current Base and Pocket Base progression.
 - [x] Dialog controls cover visitors, navigation, flight, border, spawnable overlay, boss bar, Pocket Base mob spawning, upgrades, and biome selection when applicable.
+- [x] The Pocket Base dialog shows whether owner flight still requires a successful raid or has been unlocked.
 - [x] Controls indicate their current or locked state.
 - [x] Purchases require confirmation and continue using existing validation, payment, and persistence logic.
 - [x] `ui` is offered through command autocomplete.
@@ -32,3 +33,4 @@ As a **player**, I want a dialog-based base dashboard so that I can inspect prog
 - [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md)
 - [US-018: Control Pocket Base mob spawning](us-018-control-pocket-base-mob-spawning.md)
 - [US-019: Change a Pocket Base biome](us-019-change-a-pocket-base-biome.md)
+- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md)

design/user-stories/us-021-unlock-pocket-base-flight.md

@@ -0,0 +1,37 @@
+---
+type: User Story
+title: "US-021: Unlock Pocket Base flight"
+description: Let a Pocket Base owner permanently earn controlled flight by winning a raid in their own pocket world.
+status: done
+---
+
+# US-021: Unlock Pocket Base flight
+
+As a **Pocket Base owner**, I want to earn flight by completing a raid in my Pocket Base so that I can build and travel safely throughout my expanding pocket world.
+
+## Acceptance criteria
+
+- [x] Pocket Base flight begins locked for new owners and existing saved Pocket Bases.
+- [x] A successful raid completed in a Pocket Base permanently unlocks flight only when that Pocket Base's owner is listed among the raid winners.
+- [x] Raids completed outside the owner's Pocket Base and raids the owner does not win do not unlock flight.
+- [x] Defeated, stopped, expired, and abandoned raids do not unlock flight.
+- [x] Unlocking Pocket Base flight is free and does not consume blocks or other currency.
+- [x] The owner receives a prominent one-time unlock notification after the qualifying raid.
+- [x] In Survival mode, an owner with the unlock receives plugin-granted flight while inside their own Pocket Base.
+- [x] Pocket Base flight spans the world's full build height and the current unlocked horizontal boundary plus 16 blocks on every side.
+- [x] An actively flying owner receives a warning after leaving the unlocked Pocket Base boundary while remaining inside the 16-block buffer.
+- [x] Moving beyond the 16-block buffer removes only flight granted by this plugin.
+- [x] Pocket Base expansion automatically expands the corresponding flight area.
+- [x] Visitors do not receive the owner's Pocket Base flight privilege.
+- [x] Teleportation, world changes, game-mode changes, death, logout, and plugin shutdown do not leave unintended flight enabled.
+- [x] The unlock persists across reconnects and restarts.
+- [x] Chat status and the native settings dialog show whether Pocket Base flight is locked behind a successful raid or unlocked.
+
+## Related
+
+- [US-004: Unlock and control base flight](us-004-unlock-and-control-base-flight.md)
+- [US-009: View progression and unlock notifications](us-009-view-progression-and-notifications.md)
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
+- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md)
+- [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md)
+- [US-020: Control a base through a dialog UI](us-020-control-base-through-dialog-ui.md)