feat: add stature potions and tiny-player launchers

design/index.md

@@ -0,0 +1,15 @@
+---
+type: Index
+title: Spigot Heights Design
+description: Entry point for the Spigot Heights OKF knowledge bundle.
+okf_version: "0.1"
+---
+
+# Spigot Heights Design
+
+This bundle documents craftable player-scaling potions, configurable stature limits, tiny-player dispenser launchers, persistence, and delivery requirements.
+
+## Explore
+
+- [User stories](user-stories/index.md)
+- [Design log](log.md)

design/log.md

@@ -0,0 +1,20 @@
+---
+type: Log
+title: Spigot Heights Design Log
+description: Chronological record of material decisions affecting Spigot Heights.
+---
+
+# Spigot Heights Design Log
+
+## 2026-09-04 — Initial design approved
+
+- Player scale defaults to a configurable range of `0.4` through `2.0`.
+- A moderate recipe creates a random stature potion; more expensive upgrades create targeted growth and diminution potions.
+- Random stature is selected uniformly in configurable `0.1` increments.
+- Players strictly below scale `0.5` can be launched through a dispenser fed by the hopper beneath them.
+- Launcher speed defaults to 1.5 blocks per tick with a 20-tick cooldown and safe-exit checks.
+- The project follows the neighboring Spigot Base Java 25, Purpur, Gradle, OKF, CI, and release conventions.
+
+## 2026-09-04 — Implementation started
+
+- Approved implementation began with user stories, tests, and the Gradle/Purpur foundation.

design/user-stories/index.md

@@ -0,0 +1,13 @@
+---
+type: Index
+title: Spigot Heights User Stories
+description: Catalog of user stories for the Spigot Heights plugin.
+---
+
+# Spigot Heights User Stories
+
+1. [US-001: Drink a Potion of Shifting Stature](us-001-drink-shifting-stature-potion.md)
+2. [US-002: Make precise stature adjustments](us-002-adjust-stature.md)
+3. [US-003: Launch tiny players through dispensers](us-003-launch-tiny-players.md)
+4. [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)
+5. [US-005: Build and release the plugin](us-005-build-and-release.md)

design/user-stories/us-001-drink-shifting-stature-potion.md

@@ -0,0 +1,25 @@
+---
+type: User Story
+title: "US-001: Drink a Potion of Shifting Stature"
+description: Let players craft and drink a potion that gives them a random configured scale.
+status: done
+---
+
+# US-001: Drink a Potion of Shifting Stature
+
+As a **player**, I want to drink a craftable potion that changes my stature unpredictably so that player size becomes a fun survival mechanic.
+
+## Acceptance criteria
+
+- [x] The distinct potion is authenticated with persistent item metadata rather than its display name alone.
+- [x] Its shaped recipe is `ACA/AWA/ACA`, where `A` is Amethyst Shard, `C` is Chorus Fruit, and `W` is an Awkward Potion.
+- [x] Drinking it consumes one potion, leaves normal bottle handling intact, and selects a scale from the configured inclusive range.
+- [x] Outcomes are uniformly selected in configured adjustment-step increments, including both endpoints when aligned.
+- [x] The resulting Minecraft scale attribute is applied and reported to the player.
+- [x] The resulting scale persists across logout, restart, world change, and death.
+- [x] Automated tests cover bounds, endpoint reachability, and recipe identity.
+
+## Related
+
+- [US-002: Make precise stature adjustments](us-002-adjust-stature.md)
+- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)

design/user-stories/us-002-adjust-stature.md

@@ -0,0 +1,24 @@
+---
+type: User Story
+title: "US-002: Make precise stature adjustments"
+description: Let players craft upgraded potions that increase or decrease scale by one configured step.
+status: done
+---
+
+# US-002: Make precise stature adjustments
+
+As a **player**, I want more expensive growth and diminution potions so that I can adjust my stature predictably.
+
+## Acceptance criteria
+
+- [x] The Potion of Growth uses `GAG/ASA/GRG`, where `G` is Gold Ingot, `A` is Amethyst Shard, `S` is an authenticated Potion of Shifting Stature, and `R` is Rabbit's Foot.
+- [x] The Potion of Diminution uses `GAG/ASA/GFG`, where `F` is Fermented Spider Eye.
+- [x] Each resulting potion has distinct persistent metadata.
+- [x] Growth adds one configured adjustment step and clamps at the maximum.
+- [x] Diminution subtracts one configured adjustment step and clamps at the minimum.
+- [x] Adjusted scales are reported and persisted under the same rules as random stature.
+- [x] Automated tests cover adjustment, clamping, and potion identity.
+
+## Related
+
+- [US-001: Drink a Potion of Shifting Stature](us-001-drink-shifting-stature-potion.md)

design/user-stories/us-003-launch-tiny-players.md

@@ -0,0 +1,25 @@
+---
+type: User Story
+title: "US-003: Launch tiny players through dispensers"
+description: Launch sufficiently small players from a dispenser connected to the hopper beneath them.
+status: done
+---
+
+# US-003: Launch tiny players through dispensers
+
+As a **tiny player**, I want connected hoppers and dispensers to act as launch tubes so that my stature enables playful transport systems.
+
+## Acceptance criteria
+
+- [x] A player strictly below the configured threshold triggers when walking onto a hopper whose output points into a dispenser.
+- [x] No redstone signal is required.
+- [x] The player moves to a safe centered position immediately in front of the dispenser and receives velocity in its facing direction.
+- [x] Velocity magnitude and cooldown are configurable and default to 1.5 blocks per tick and 20 ticks.
+- [x] Obstructed or unsafe exits abort without moving the player.
+- [x] Players at or above the threshold are not launched.
+- [x] Cooldown prevents immediate repeated or cyclic launching.
+- [x] Automated tests cover threshold boundaries, orientations, cooldown, and obstruction policy.
+
+## Related
+
+- [US-004: Configure and persist stature behavior](us-004-configure-and-persist.md)

design/user-stories/us-004-configure-and-persist.md

@@ -0,0 +1,25 @@
+---
+type: User Story
+title: "US-004: Configure and persist stature behavior"
+description: Give operators validated settings and durable UUID-keyed player scales.
+status: done
+---
+
+# US-004: Configure and persist stature behavior
+
+As a **server operator**, I want validated stature and launcher settings with durable state so that behavior remains safe and predictable.
+
+## Acceptance criteria
+
+- [x] Defaults are minimum `0.4`, maximum `2.0`, adjustment step `0.1`, launcher threshold `0.5`, speed `1.5`, and cooldown `20` ticks.
+- [x] Configuration requires finite positive values, minimum no greater than maximum, and a launcher threshold within the supported scale range.
+- [x] Invalid startup configuration disables the plugin with a clear error.
+- [x] Player scales are stored by UUID using atomic file replacement where supported.
+- [x] Updating known state preserves unknown forward-compatible YAML fields.
+- [x] Missing state defaults safely to scale `1.0` clamped to the configured range.
+- [x] Saved out-of-range state is clamped before it is applied.
+- [x] Configuration and state behavior have automated tests.
+
+## Related
+
+- [User-story catalog](index.md)

design/user-stories/us-005-build-and-release.md

@@ -0,0 +1,24 @@
+---
+type: User Story
+title: "US-005: Build and release the plugin"
+description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases.
+status: in-progress
+---
+
+# US-005: Build and release the plugin
+
+As a **plugin maintainer**, I want automated builds and releases modeled on Spigot Base so that tested artifacts can be distributed consistently.
+
+## Acceptance criteria
+
+- [ ] Gradle compiles against Purpur API `26.2.build.2618-stable` using Java 25.
+- [ ] Compiler lint warnings fail the build and JUnit 5 tests run during `check`.
+- [ ] Gitea Actions verifies pushes and pull requests and stores a development JAR.
+- [ ] Pull requests validate conventional commits.
+- [ ] Main-branch conventional commits drive semantic releases and attach versioned JARs to Gitea releases.
+- [ ] The README documents requirements, recipes, configuration, building, and releases.
+- [ ] `./gradlew clean check jar` succeeds.
+
+## Related
+
+- [User-story catalog](index.md)