feat(pocket-base): share flight through gold portals

design/log.md

@@ -156,3 +156,11 @@ description: Chronological record of material decisions affecting the Spigot Bas
 - 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`.
+
+## 2026-08-28 — Shared Pocket Base flight portals
+
+- Added one persistent owner-activated gold-block flight portal per Pocket Base after the raid unlock.
+- Granted owners and guests temporary controlled flight after portal collision, independently of the owner's persisted automatic-flight preference.
+- Applied the expanding Pocket Base boundary plus a 16-block warning buffer to both automatic and portal-granted flight.
+- Restored Back buttons from nested native dialog screens to the main Base Settings dashboard.
+- Verified 149 tests and the Java 25 plugin artifact with `./gradlew clean check jar`.

design/user-stories/index.md

@@ -27,3 +27,4 @@ description: Catalog of user stories for the Spigot Base plugin.
 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)
+22. [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md)

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

@@ -18,6 +18,7 @@ As a **server operator**, I want progression behavior to be configurable and dur
 - [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] Pocket Base state persists the owner automatic-flight preference and active flight portal, with safe defaults for legacy records.
 - [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.
@@ -30,3 +31,4 @@ As a **server operator**, I want progression behavior to be configurable and dur
 - [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)
+- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md)

design/user-stories/us-016-build-and-use-pocket-base-portals.md

@@ -37,6 +37,7 @@ As a **Pocket Base owner**, I want to connect my normal base to my Pocket Base w
 - [x] Players who disconnect inside a Pocket Base remain there when they reconnect.
 - [x] Moving the normal base deactivates its entrance while preserving the Pocket Base world and its contents.
 - [x] Portal ownership and the active entrance location persist through restarts.
+- [x] A separate active gold-block portal inside an owner's Pocket Base can grant temporary controlled flight after raid-earned flight is unlocked.
 
 ## Related
 
@@ -44,3 +45,4 @@ As a **Pocket Base owner**, I want to connect my normal base to my Pocket Base w
 - [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.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-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md)

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

@@ -16,7 +16,8 @@ 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] The Pocket Base dialog shows whether owner flight still requires a successful raid and lets an unlocked owner enable or disable automatic Pocket Base flight.
+- [x] Nested dialog screens provide Back buttons that return to the main Base Settings dashboard.
 - [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.
@@ -34,3 +35,4 @@ As a **player**, I want a dialog-based base dashboard so that I can inspect prog
 - [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)
+- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md)

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

@@ -17,7 +17,7 @@ As a **Pocket Base owner**, I want to earn flight by completing a raid in my Poc
 - [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] In Survival mode, an owner with the unlock can enable or disable automatic plugin-granted flight inside their own Pocket Base without affecting portal-granted temporary flight.
 - [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.
@@ -35,3 +35,4 @@ As a **Pocket Base owner**, I want to earn flight by completing a raid in my Poc
 - [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)
+- [US-022: Share Pocket Base flight through a portal](us-022-share-pocket-base-flight-through-a-portal.md)

design/user-stories/us-022-share-pocket-base-flight-through-a-portal.md

@@ -0,0 +1,35 @@
+---
+type: User Story
+title: "US-022: Share Pocket Base flight through a portal"
+description: Let an owner build a gold-block portal that temporarily grants controlled Pocket Base flight to players who pass through it.
+status: done
+---
+
+# US-022: Share Pocket Base flight through a portal
+
+As a **Pocket Base owner**, I want an activated flight portal inside my Pocket Base so that I can temporarily share controlled flight with guests without changing my own default-flight preference.
+
+## Acceptance criteria
+
+- [x] The owner must first unlock Pocket Base flight by winning a raid in their own Pocket Base.
+- [x] Only the owner can activate a complete 4-by-5 gold-block frame with flint and steel as the active flight portal.
+- [x] Every required frame block must be inside the owner's currently unlocked Pocket Base boundary at activation.
+- [x] Each Pocket Base has at most one active flight portal, and activating another valid frame moves the active location without removing the old frame.
+- [x] The active flight portal uses custom particles and collision without vanilla Nether portal blocks.
+- [x] Breaking any required block in the active frame deactivates the flight portal.
+- [x] Any player, including the owner or a guest, who passes through the active intact flight portal receives temporary Pocket Base flight.
+- [x] Portal-granted flight remains independent of the owner's default Pocket Base flight preference.
+- [x] Portal-granted flight spans the world's full build height and the current Pocket Base boundary plus 16 blocks on every side.
+- [x] An actively flying player receives a warning inside the 16-block buffer, and flight ends beyond it.
+- [x] Expanding the Pocket Base automatically expands the portal-granted flight area.
+- [x] Portal-granted flight ends when the player leaves the Pocket Base, dies, disconnects, or changes out of Survival mode.
+- [x] The active flight portal location and owner default-flight preference persist across restarts.
+- [x] Existing saved Pocket Bases default to no flight portal while preserving raid-earned owner flight as enabled.
+
+## Related
+
+- [US-011: Configure and persist progression](us-011-configure-and-persist-progression.md)
+- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.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)
+- [US-021: Unlock Pocket Base flight](us-021-unlock-pocket-base-flight.md)