chore(knowledge): move canonical docs to shared SoMC wiki

AGENTS.md

@@ -1,37 +1,9 @@
-# Project Agent Instructions
+# spigot-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/spigot-inventory-helper/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-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/spigot-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

@@ -2,7 +2,7 @@
 
 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/spigot-inventory-helper/index.md).
 
 ## Requirements
 

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)