feat(inventory): adopt Purpur distribution naming

BREAKING CHANGE: New release assets use purpur-inventory-helper-<version>.jar. Runtime SpigotInventoryHelper identity and existing sorting-stick/recipe keys remain unchanged. Replace the old JAR rather than installing both distributions.

.gitea/workflows/ci.yml

@@ -35,6 +35,6 @@ jobs:
       - name: Upload development artifact
         uses: actions/upload-artifact@v3
         with:
-          name: spigot-inventory-helper-${{ github.sha }}
+          name: purpur-inventory-helper-${{ github.sha }}
           path: build/libs/*.jar
           if-no-files-found: error

.gitea/workflows/release.yml

@@ -86,8 +86,8 @@ jobs:
         if: steps.release.outputs.created == 'true'
         uses: actions/upload-artifact@v3
         with:
-          name: spigot-inventory-helper-${{ steps.release.outputs.version }}
-          path: build/libs/spigot-inventory-helper-${{ steps.release.outputs.version }}.jar
+          name: purpur-inventory-helper-${{ steps.release.outputs.version }}
+          path: build/libs/purpur-inventory-helper-${{ steps.release.outputs.version }}.jar
           if-no-files-found: error
 
       - name: Create Gitea release and upload plugin
@@ -101,7 +101,7 @@ jobs:
           PREVIOUS_TAG: ${{ steps.previous_tag.outputs.value }}
         run: |
           api_url="${GITEA_SERVER_URL}/api/v1"
-          jar="build/libs/spigot-inventory-helper-${VERSION}.jar"
+          jar="build/libs/purpur-inventory-helper-${VERSION}.jar"
           export RELEASE_BODY
           if [ -n "$PREVIOUS_TAG" ]; then
             RELEASE_BODY=$(git log --pretty='format:- %s (%h)' "${PREVIOUS_TAG}..HEAD")
@@ -138,4 +138,4 @@ jobs:
             -H "Authorization: token ${GITEA_TOKEN}" \
             -H "Content-Type: application/octet-stream" \
             --data-binary "@${jar}" \
-            "${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=spigot-inventory-helper-${VERSION}.jar"
+            "${api_url}/repos/${REPOSITORY}/releases/${release_id}/assets?name=purpur-inventory-helper-${VERSION}.jar"

AGENTS.md

@@ -1,37 +1,9 @@
-# Project Agent Instructions
+# purpur-inventory-helper agent entrypoint
 
-## Project
+The canonical stories, engineering guidance, and **all process documents** are in the private [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/index.md).
 
-- This repository contains the Spigot Inventory Helper plugin.
-- Target Purpur `26.2.build.2618-stable` with Java 25, matching `../spigot-base/` unless an approved user story changes the target.
-- Use Gradle with Kotlin DSL and the Gradle wrapper.
-- Keep compiler lint warnings enabled and fail builds on warnings, excluding only warnings explicitly justified by the supported API.
+Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/purpur-inventory-helper/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/purpur-inventory-helper/` stories. Also follow the parent workspace `AGENTS.md` when present.
 
-## Knowledge bundle
+For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/purpur-inventory-helper/index.md) and [shared process](https://git.garvis.dev/dmg/somc-okf/src/branch/main/processes/development.md). Obtain wiki access before feature work; do not recreate a local knowledge bundle. Source builds do not require private wiki access.
 
-- `design/` is the canonical OKF v0.1 knowledge bundle. Do not create a parallel `knowledge/` bundle.
-- Read `design/index.md`, the user-story catalog, relevant stories, and relevant implementation before changing behavior.
-- Every feature or behavior change must have a corresponding story under `design/user-stories/`.
-- Present proposed story additions or changes for review and wait for explicit approval before modifying stories or code.
-- Stories must have OKF frontmatter with `type: User Story`, a descriptive `title`, concise `description`, and one of `backlog`, `in-progress`, or `done` as `status`.
-- Stories must contain acceptance criteria using Markdown task-list items.
-- Set approved work to `in-progress` when implementation begins. Set it to `done` and check criteria only after implementation and verification.
-- Maintain standard Markdown links between the root index, story catalog, related stories, and other concepts.
-- Record material design and implementation decisions in `design/log.md`. Verify the current date before adding entries.
-
-## Development
-
-- Use test-driven development where practical: write a failing test, implement the minimum behavior, and refactor only while tests remain green.
-- Prefer small, cohesive Java types and server-independent logic that can be unit tested without a running Minecraft server.
-- Identify custom plugin items with persistent metadata rather than display names alone.
-- Preserve item quantities and metadata during inventory operations.
-- Respect Bukkit/Purpur event cancellation and protection-plugin decisions.
-- Run `./gradlew clean check jar` before marking implementation criteria complete.
-
-## Delivery
-
-- Model Gradle and Gitea Actions configuration on `../spigot-base/`, adapted to this plugin's names and identifiers.
-- Gitea workflows belong in `.gitea/workflows/`.
-- Pull requests must validate conventional commits, and main-branch conventional commits drive semantic releases.
-- Never commit generated Gradle output or plugin JARs.
-- Use conventional commit messages in the form `type(scope): description`, with a concise summary under 72 characters.
+Development follows [Development cycle](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/development-cycle.md): approved stories, failing tests, passing implementation, verification, then source/wiki commit and push. GitOps updates are committed locally **without pushing**; only [Do release](https://git.garvis.dev/dmg/somc-okf/src/branch/main/runbooks/do-release.md) authorizes a reviewed GitOps push.

README.md

@@ -1,8 +1,10 @@
-# Spigot Inventory Helper
+# Purpur Inventory Helper
 
 A Purpur 26.2 plugin that sorts inventories with a craftable Sorting Stick and automatically replaces broken tools with equivalent tools from the player's inventory.
 
-The approved behavior is specified in the [OKF design bundle](design/index.md).
+The approved behavior is specified in the [SoMC OKF wiki](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/purpur-inventory-helper/index.md).
+
+The repository, checkout and new JARs use `purpur-inventory-helper`. Runtime `SpigotInventoryHelper`, Java entrypoint/packages, data namespace and sorting-stick/recipe keys remain unchanged. Replace the old JAR instead of loading both distributions. Old tags and `spigot-inventory-helper-*` assets are retained; the previous v1.2.0 download was checked for identical bytes after the rename.
 
 ## Requirements
 

build.gradle.kts

@@ -35,6 +35,9 @@ dependencies {
 
 tasks.test {
     useJUnitPlatform()
+    dependsOn(tasks.jar)
+    systemProperty("distribution.jar", tasks.jar.get().archiveFile.get().asFile.absolutePath)
+    systemProperty("distribution.version", project.version.toString())
 }
 
 val pluginVersion = version

design/index.md

@@ -1,15 +0,0 @@
----
-type: Index
-title: Spigot Inventory Helper Design
-description: Entry point for the Spigot Inventory Helper OKF knowledge bundle.
-okf_version: "0.1"
----
-
-# Spigot Inventory Helper Design
-
-This bundle documents inventory sorting, custom utility items, automatic tool replacement, and delivery requirements for the Spigot Inventory Helper plugin.
-
-## Explore
-
-- [User stories](user-stories/index.md)
-- [Design log](log.md)

design/log.md

@@ -1,51 +0,0 @@
----
-type: Log
-title: Spigot Inventory Helper Design Log
-description: Chronological record of material decisions affecting the Spigot Inventory Helper design.
----
-
-# Spigot Inventory Helper Design Log
-
-## 2026-09-04 — Initial inventory-helper design
-
-- Players will be able to craft a metadata-authenticated Sorting Stick.
-- The Sorting Stick will sort chests, double chests, barrels, or the player's main storage inventory depending on the interaction target.
-- Player-inventory sorting will leave the hotbar, armor, and off-hand slots unchanged.
-- When a main-hand tool breaks, an equivalent tool with the same material and tool type will be moved from the player's inventory into the selected hotbar slot when available.
-- The knowledge bundle and eventual Gradle, Purpur, Gitea CI, and semantic-release setup will follow the neighboring Spigot Base project where applicable.
-
-## 2026-09-04 — Sorting Stick recipe
-
-- The Sorting Stick uses a vertical recipe in the crafting grid's center column: a Chest or Barrel above Redstone Dust, with a Stick at the bottom.
-- Either storage-block variant produces one Sorting Stick.
-
-## 2026-09-04 — Build and release foundation completed
-
-- Added the Java 25 Gradle build, Purpur API dependency, strict compiler linting, JUnit 5 lifecycle, plugin metadata, and initial plugin entry point.
-- Added Gitea CI, conventional-commit validation for pull requests, development artifacts, semantic releases, and release-asset upload.
-- Verified `./gradlew clean check jar`, successful main and tag CI runs, and release `v1.0.0` with `spigot-inventory-helper-1.0.0.jar` attached.
-
-## 2026-09-04 — Sorting Stick completed
-
-- Added a gold-named, glinting Sorting Stick authenticated by persistent item metadata.
-- Registered equivalent chest and barrel recipe variants matching the approved center-column shape.
-- Verified recipe specification, registration, output, item appearance, identity, and renamed-stick rejection with automated tests and `./gradlew clean check jar`.
-
-## 2026-09-04 — Inventory sorting completed
-
-- Added metadata-preserving stack consolidation and stable alphabetical ordering by Minecraft material.
-- Added Sorting Stick interactions for single and double chests, barrels, and player main-storage slots while preserving hotbar, armor, and off-hand slots.
-- Rejected locked containers, cancelled protection events, non-right-click interactions, and unauthenticated sticks without changing inventories.
-- Added action-bar feedback, documented player behavior, and verified the complete feature with `./gradlew clean check jar`.
-
-## 2026-09-04 — Automatic tool replacement completed
-
-- Added next-tick replacement of broken main-hand tools with exact-material matches from player storage.
-- Main storage is searched before other hotbar slots, and the replacement item is moved intact into the captured selected slot without overwriting a newly occupied slot.
-- Off-hand breaks and unavailable or mismatched replacements leave inventory unchanged.
-- Added player feedback and verified matching, source priority, metadata-preserving movement, safety, and off-hand behavior with automated tests and `./gradlew clean check jar`.
-
-## 2026-09-04 — Implementation started
-
-- Approved implementation begins with the tested Gradle and Purpur foundation, followed by the Sorting Stick, inventory sorting, and automatic tool replacement.
-- Work proceeds one user story at a time using red-green-refactor cycles and a verified commit and push after each completed story.

design/user-stories/index.md

@@ -1,12 +0,0 @@
----
-type: Index
-title: Spigot Inventory Helper User Stories
-description: Catalog of user stories for the Spigot Inventory Helper plugin.
----
-
-# Spigot Inventory Helper User Stories
-
-1. [US-001: Build and release the plugin](us-001-build-and-release-plugin.md)
-2. [US-002: Craft a Sorting Stick](us-002-craft-sorting-stick.md)
-3. [US-003: Sort containers and player inventory](us-003-sort-inventories.md)
-4. [US-004: Automatically replace broken tools](us-004-replace-broken-tools.md)

design/user-stories/us-001-build-and-release-plugin.md

@@ -1,26 +0,0 @@
----
-type: User Story
-title: "US-001: Build and release the plugin"
-description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases.
-status: done
----
-
-# US-001: Build and release the plugin
-
-As a **plugin maintainer**, I want repeatable builds and automated releases so that tested, correctly versioned artifacts can be distributed consistently.
-
-## Acceptance criteria
-
-- [x] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain.
-- [x] Compiler lint warnings fail the build.
-- [x] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
-- [x] Pushes and pull requests build and test the plugin in Gitea Actions.
-- [x] Pull requests validate conventional commit messages.
-- [x] CI stores a development JAR as a workflow artifact.
-- [x] Main-branch conventional commits drive semantic versioning.
-- [x] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
-- [x] Build files, Gradle wrapper, workflows, and release behavior follow `../spigot-base/` where applicable while using Spigot Inventory Helper names and identifiers.
-
-## Related
-
-- [User-story catalog](index.md)

design/user-stories/us-002-craft-sorting-stick.md

@@ -1,26 +0,0 @@
----
-type: User Story
-title: "US-002: Craft a Sorting Stick"
-description: Let players craft a recognizable utility item that invokes inventory sorting.
-status: done
----
-
-# US-002: Craft a Sorting Stick
-
-As a **player**, I want to craft a recognizable Sorting Stick so that I can invoke inventory sorting during normal gameplay.
-
-## Acceptance criteria
-
-- [x] The plugin registers a vertical shaped recipe with a Chest or Barrel above Redstone Dust and Redstone Dust above a Stick.
-- [x] The three ingredients occupy the center column of the 3×3 crafting grid.
-- [x] Either the Chest or Barrel recipe variant produces one Sorting Stick.
-- [x] The Sorting Stick has a distinct player-facing name and appearance.
-- [x] The item is identified using persistent item metadata rather than its display name alone.
-- [x] Renamed ordinary sticks cannot trigger sorting.
-- [x] Automated tests cover recipe registration, the exact shape, both storage-block variants, output quantity, and resulting item identity.
-- [x] The crafting recipe and both accepted variants are documented for players.
-
-## Related
-
-- [US-003: Sort containers and player inventory](us-003-sort-inventories.md)
-- [User-story catalog](index.md)

design/user-stories/us-003-sort-inventories.md

@@ -1,30 +0,0 @@
----
-type: User Story
-title: "US-003: Sort containers and player inventory"
-description: Let players use a Sorting Stick to consolidate and organize supported storage or their main inventory.
-status: done
----
-
-# US-003: Sort containers and player inventory
-
-As a **player holding a Sorting Stick**, I want to sort storage containers or my main inventory so that related items are consolidated and organized automatically.
-
-## Acceptance criteria
-
-- [x] Using the Sorting Stick on a chest sorts the complete chest inventory.
-- [x] Using it on either half of a double chest sorts the combined inventory.
-- [x] Using it on a barrel sorts that barrel.
-- [x] Using it without targeting a supported container sorts the player's main storage slots.
-- [x] Player hotbar, armor, and off-hand slots are not changed during player-inventory sorting.
-- [x] Compatible partial stacks are consolidated without exceeding item stack limits.
-- [x] Remaining stacks are placed in a deterministic, documented order.
-- [x] Sorting preserves item quantities and all item metadata exactly.
-- [x] Sorting respects cancelled interactions and normal container-access protections.
-- [x] Unsupported or inaccessible targets fail safely without changing an inventory.
-- [x] Sorting provides concise player feedback without opening the target container.
-- [x] Automated tests cover single chests, double chests, barrels, player inventory boundaries, stack consolidation, metadata preservation, and rejected interactions.
-
-## Related
-
-- [US-002: Craft a Sorting Stick](us-002-craft-sorting-stick.md)
-- [User-story catalog](index.md)

design/user-stories/us-004-replace-broken-tools.md

@@ -1,26 +0,0 @@
----
-type: User Story
-title: "US-004: Automatically replace broken tools"
-description: Move an equivalent inventory tool into the player's hand when their current main-hand tool breaks.
-status: done
----
-
-# US-004: Automatically replace broken tools
-
-As a **player**, I want an equivalent tool moved into my hand when my current tool breaks so that I can continue working without searching my inventory.
-
-## Acceptance criteria
-
-- [x] When a player's main-hand tool breaks, the plugin searches the player's inventory for a replacement.
-- [x] A replacement must have the same tool type and material as the broken tool; for example, a diamond pickaxe replaces only a diamond pickaxe.
-- [x] Eligible replacements may come from the main storage inventory or another hotbar slot.
-- [x] The replacement is moved into the currently selected hotbar slot.
-- [x] Existing durability, enchantments, custom names, persistent data, and other metadata on the replacement are preserved.
-- [x] No unrelated item is moved when an equivalent replacement is unavailable.
-- [x] Off-hand tool breakage does not replace the main-hand item.
-- [x] Cancelled damage or break events do not trigger replacement.
-- [x] Automated tests cover matching, unavailable replacements, hotbar and main-storage candidates, metadata preservation, and off-hand behavior.
-
-## Related
-
-- [User-story catalog](index.md)

settings.gradle.kts

@@ -2,4 +2,4 @@ plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
 }
 
-rootProject.name = "spigot-inventory-helper"
+rootProject.name = "purpur-inventory-helper"

src/test/java/games/dmg/spigotinventoryhelper/PurpurDistributionTest.java

@@ -0,0 +1,56 @@
+package games.dmg.spigotinventoryhelper;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.DataInputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.jar.JarFile;
+import org.junit.jupiter.api.Test;
+import org.yaml.snakeyaml.Yaml;
+
+class PurpurDistributionTest {
+    @Test
+    void packagesNewNameWithoutChangingRuntimeIdentityOrBundlingTheApi() throws Exception {
+        Path artifact = Path.of(System.getProperty("distribution.jar"));
+        String version = System.getProperty("distribution.version");
+        assertEquals("purpur-inventory-helper-" + version + ".jar", artifact.getFileName().toString());
+        try (var jar = new JarFile(artifact.toFile())) {
+            Map<?, ?> metadata = new Yaml().load(jar.getInputStream(jar.getJarEntry("plugin.yml")));
+            assertEquals(version, metadata.get("version"));
+            assertEquals("SpigotInventoryHelper", metadata.get("name"), "Retain the data directory and persistent namespace");
+            assertEquals("games.dmg.spigotinventoryhelper.SpigotInventoryHelperPlugin", metadata.get("main"));
+            assertFalse(metadata.containsKey("permissions"));
+            assertFalse(metadata.containsKey("commands"));
+            var description = new org.bukkit.plugin.PluginDescriptionFile(jar.getInputStream(jar.getJarEntry("plugin.yml")));
+            assertEquals("spigotinventoryhelper", description.namespace(), "Persistent sorting-stick namespace must survive distribution renaming");
+            assertFalse(jar.stream().anyMatch(entry -> entry.getName().startsWith("org/bukkit/")
+                || entry.getName().startsWith("org/purpurmc/") || entry.getName().endsWith("Test.class")));
+        }
+    }
+
+    @Test
+    void pluginBytecodeTargetsJava25() throws Exception {
+        try (var jar = new JarFile(System.getProperty("distribution.jar"));
+             var bytecode = new DataInputStream(jar.getInputStream(
+                 jar.getJarEntry("games/dmg/spigotinventoryhelper/SpigotInventoryHelperPlugin.class")))) {
+            assertEquals(0xCAFEBABE, bytecode.readInt());
+            bytecode.readUnsignedShort();
+            assertEquals(69, bytecode.readUnsignedShort());
+        }
+    }
+
+    @Test
+    void releaseAndCiAgreeWithThePurpurDistributionNameAndToolchain() throws Exception {
+        String build = Files.readString(Path.of("build.gradle.kts"));
+        assertTrue(build.contains("purpur-api:26.2.build.2618-stable"));
+        assertFalse(build.contains("org.spigotmc:spigot-api"));
+        for (String workflow : new String[] {"ci.yml", "release.yml"}) {
+            String content = Files.readString(Path.of(".gitea/workflows", workflow));
+            assertTrue(content.contains("java-version: 25"));
+            assertTrue(content.contains("purpur-inventory-helper-"), workflow);
+            assertFalse(content.contains("spigot-inventory-helper-"), workflow);
+        }
+    }
+}