feat(pocket-base): add persistent pocket dimensions

design/user-stories/index.md

@@ -20,3 +20,6 @@ description: Catalog of user stories for the Spigot Base plugin.
 12. [US-012: Build and release the plugin](us-012-build-and-release-plugin.md)
 13. [US-013: Visualize the base border](us-013-visualize-base-border.md)
 14. [US-014: Highlight spawnable blocks](us-014-highlight-spawnable-blocks.md)
+15. [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md)
+16. [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md)
+17. [US-017: Expand a Pocket Base](us-017-expand-a-pocket-base.md)

design/user-stories/us-008-unlock-visitor-access.md

@@ -37,3 +37,5 @@ As a **player with Base III**, I want to open my base to visitors so that other
 - [US-005: Unlock Base III teleportation](us-005-unlock-base-teleportation.md)
 - [US-006: Reduce the base teleport warm-up](us-006-reduce-teleport-warmup.md)
 - [US-007: Reduce the base teleport cooldown](us-007-reduce-teleport-cooldown.md)
+- [US-015: Unlock a Pocket Base](us-015-unlock-a-pocket-base.md)
+- [US-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md)

design/user-stories/us-015-unlock-a-pocket-base.md

@@ -0,0 +1,30 @@
+---
+type: User Story
+title: "US-015: Unlock a Pocket Base"
+description: Let Base IV owners purchase a persistent private void world that serves as the foundation for portal access and expansion.
+status: done
+---
+
+# US-015: Unlock a Pocket Base
+
+As a **player with an established Base IV**, I want to unlock a persistent Pocket Base so that I can build in a personal space beyond the normal world.
+
+## Acceptance criteria
+
+- [x] Pocket Base progression requires an established Base IV.
+- [x] `/basesettings pocket upgrade` unlocks Pocket Base I and is offered through contextual autocomplete.
+- [x] Unlocking atomically charges a configurable currency and amount that default to 64 diamond blocks.
+- [x] Insufficient funds or failed persistence or world creation does not consume currency or grant Pocket Base I.
+- [x] Pocket Base I creates a persistent owner-specific void world keyed by the owner's UUID.
+- [x] The initial platform is 64 by 64 blocks with one grass layer over three dirt layers.
+- [x] The pocket world provides a safe arrival location and a generated return portal.
+- [x] Pocket Base worlds, contents, ownership, and progression persist through reconnects, restarts, and normal-base relocation.
+- [x] `/basesettings status` displays the current Pocket Base level and the next upgrade requirement.
+
+## Related
+
+- [US-008: Unlock Base IV visitor access](us-008-unlock-visitor-access.md)
+- [US-009: View progression and notifications](us-009-view-progression-and-notifications.md)
+- [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)

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

@@ -0,0 +1,35 @@
+---
+type: User Story
+title: "US-016: Build and use Pocket Base portals"
+description: Let an owner create one public portal between their normal base and persistent Pocket Base.
+status: done
+---
+
+# US-016: Build and use Pocket Base portals
+
+As a **Pocket Base owner**, I want to connect my normal base to my Pocket Base with a public portal so that I and other players can move between them naturally.
+
+## Acceptance criteria
+
+- [x] The entrance uses a standard 4-by-5 outer frame with a 2-by-3 interior and a configurable frame material that defaults to diamond blocks.
+- [x] Only the Pocket Base owner can activate a complete entrance frame with flint and steel.
+- [x] Every required frame block must be within the owner's current normal-base bounds when the entrance is activated.
+- [x] Custom particles and collision provide portal-like visuals and travel without relying on vanilla Nether portal blocks.
+- [x] Each owner has at most one active entrance portal.
+- [x] Activating another valid entrance deactivates the previous entrance without removing its frame blocks.
+- [x] Breaking any required frame block immediately deactivates the entrance.
+- [x] Any player can use an active entrance without a separate visitor setting, warm-up, or cooldown.
+- [x] Visitors can build, break blocks, open containers, and otherwise interact normally inside the Pocket Base.
+- [x] The generated return portal sends players safely to the owner's active entrance.
+- [x] Return travel falls back to the server spawn when the owner has no valid active entrance.
+- [x] Falling below Y -64 performs the same safe return without void damage.
+- [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.
+
+## Related
+
+- [US-003: Expand the base](us-003-expand-the-base.md)
+- [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)

design/user-stories/us-017-expand-a-pocket-base.md

@@ -0,0 +1,28 @@
+---
+type: User Story
+title: "US-017: Expand a Pocket Base"
+description: Let Pocket Base owners purchase unlimited levels that add permanent buildable terrain around their pocket world.
+status: done
+---
+
+# US-017: Expand a Pocket Base
+
+As a **Pocket Base owner**, I want to purchase additional buildable space so that my pocket world can grow with my projects.
+
+## Acceptance criteria
+
+- [x] Using `/basesettings pocket upgrade` after Pocket Base I purchases the next Pocket Base level.
+- [x] Each additional level atomically charges a configurable currency and amount that default to 16 diamond blocks.
+- [x] Insufficient funds or failed persistence or terrain generation does not consume currency or grant a level.
+- [x] Each level adds 16 blocks on every side, producing Level I at 64 by 64, Level II at 96 by 96, Level III at 128 by 128, and size `64 + 32 × (level - 1)` thereafter.
+- [x] Newly unlocked terrain has one grass layer over three dirt layers.
+- [x] Expansion preserves all existing blocks, inventories, and entities in previously unlocked terrain.
+- [x] Owners and visitors cannot place blocks outside the currently unlocked horizontal boundary.
+- [x] Pocket Base progression has no plugin-configured level cap, subject only to Minecraft coordinate and integer limits.
+- [x] Pocket Base levels, dimensions, contents, and build boundaries persist through restarts.
+
+## Related
+
+- [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-016: Build and use Pocket Base portals](us-016-build-and-use-pocket-base-portals.md)