docs: add initial design bundle

AGENTS.md

@@ -0,0 +1,37 @@
+# Project Agent Instructions
+
+## Project
+
+- 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.
+
+## Knowledge bundle
+
+- `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.

design/index.md

@@ -0,0 +1,15 @@
+---
+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

@@ -0,0 +1,15 @@
+---
+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.

design/user-stories/index.md

@@ -0,0 +1,12 @@
+---
+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

@@ -0,0 +1,26 @@
+---
+type: User Story
+title: "US-001: Build and release the plugin"
+description: Give maintainers repeatable Purpur builds, automated verification, and versioned Gitea releases.
+status: backlog
+---
+
+# 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
+
+- [ ] The Gradle project compiles against Purpur API `26.2.build.2618-stable` using a Java 25 toolchain.
+- [ ] Compiler lint warnings fail the build.
+- [ ] Automated JUnit 5 tests run as part of the Gradle check lifecycle.
+- [ ] Pushes and pull requests build and test the plugin in Gitea Actions.
+- [ ] Pull requests validate conventional commit messages.
+- [ ] CI stores a development JAR as a workflow artifact.
+- [ ] Main-branch conventional commits drive semantic versioning.
+- [ ] A successful release builds a versioned JAR and attaches it to the corresponding Gitea release.
+- [ ] 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

@@ -0,0 +1,24 @@
+---
+type: User Story
+title: "US-002: Craft a Sorting Stick"
+description: Let players craft a recognizable utility item that invokes inventory sorting.
+status: backlog
+---
+
+# 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
+
+- [ ] The plugin registers a documented shaped crafting recipe for the Sorting Stick.
+- [ ] The Sorting Stick has a distinct player-facing name and appearance.
+- [ ] The item is identified using persistent item metadata rather than its display name alone.
+- [ ] Renamed ordinary sticks cannot trigger sorting.
+- [ ] Recipe registration, recipe shape, and resulting item identity are covered by automated tests.
+- [ ] The crafting recipe is 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

@@ -0,0 +1,30 @@
+---
+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: backlog
+---
+
+# 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
+
+- [ ] Using the Sorting Stick on a chest sorts the complete chest inventory.
+- [ ] Using it on either half of a double chest sorts the combined inventory.
+- [ ] Using it on a barrel sorts that barrel.
+- [ ] Using it without targeting a supported container sorts the player's main storage slots.
+- [ ] Player hotbar, armor, and off-hand slots are not changed during player-inventory sorting.
+- [ ] Compatible partial stacks are consolidated without exceeding item stack limits.
+- [ ] Remaining stacks are placed in a deterministic, documented order.
+- [ ] Sorting preserves item quantities and all item metadata exactly.
+- [ ] Sorting respects cancelled interactions and normal container-access protections.
+- [ ] Unsupported or inaccessible targets fail safely without changing an inventory.
+- [ ] Sorting provides concise player feedback without opening the target container.
+- [ ] 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

@@ -0,0 +1,26 @@
+---
+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: backlog
+---
+
+# 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
+
+- [ ] When a player's main-hand tool breaks, the plugin searches the player's inventory for a replacement.
+- [ ] A replacement must have the same tool type and material as the broken tool; for example, a diamond pickaxe replaces only a diamond pickaxe.
+- [ ] Eligible replacements may come from the main storage inventory or another hotbar slot.
+- [ ] The replacement is moved into the currently selected hotbar slot.
+- [ ] Existing durability, enchantments, custom names, persistent data, and other metadata on the replacement are preserved.
+- [ ] No unrelated item is moved when an equivalent replacement is unavailable.
+- [ ] Off-hand tool breakage does not replace the main-hand item.
+- [ ] Cancelled damage or break events do not trigger replacement.
+- [ ] Automated tests cover matching, unavailable replacements, hotbar and main-storage candidates, metadata preservation, and off-hand behavior.
+
+## Related
+
+- [User-story catalog](index.md)