docs(design): add user story knowledge bundle

design/index.md

@@ -0,0 +1,16 @@
+---
+type: Index
+title: Spigot Event Producer Design
+description: Entry point for the Spigot Event Producer OKF knowledge bundle.
+okf_version: "0.1"
+---
+
+# Spigot Event Producer Design
+
+This bundle documents the user-visible and operational behavior of the Spigot plugin that captures Minecraft activity and delivers it as CloudEvents.
+
+## Explore
+
+- [User stories](user-stories/index.md)
+- [Design log](log.md)
+- [Project README](../README.md)

design/log.md

@@ -0,0 +1,12 @@
+---
+type: Log
+title: Design Log
+description: Chronological record of material changes to the design knowledge bundle.
+---
+
+# Design Log
+
+## 2026-08-08
+
+- Established the OKF v0.1 design bundle.
+- Documented the existing configuration, event production, activity capture, snapshots, durable delivery, and release workflows as user stories.

design/user-stories/index.md

@@ -0,0 +1,16 @@
+---
+type: Index
+title: User Stories
+description: Catalog of user stories for the Spigot Event Producer.
+---
+
+# User Stories
+
+1. [US-001: Configure the event producer](us-001-configure-event-producer.md)
+2. [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+3. [US-003: Capture player and server activity](us-003-capture-player-activity.md)
+4. [US-004: Capture periodic player snapshots](us-004-capture-player-snapshots.md)
+5. [US-005: Deliver events durably](us-005-deliver-events-durably.md)
+6. [US-006: Build and release the plugin](us-006-build-and-release-plugin.md)
+
+Return to the [design index](../index.md).

design/user-stories/us-001-configure-event-producer.md

@@ -0,0 +1,24 @@
+---
+type: User Story
+title: "US-001: Configure the event producer"
+description: Allow a server operator to identify a Minecraft server and tune event capture and delivery safely.
+status: done
+---
+
+# US-001: Configure the event producer
+
+As a **Minecraft server operator**, I want to configure the producer for my server and ingest service so that emitted events are identifiable and fit my operating limits.
+
+## Acceptance criteria
+
+- [x] A human-readable server name and stable server UUID can be configured.
+- [x] When no server UUID is supplied, the plugin generates one and persists it for later starts.
+- [x] The ingest URL, send interval, snapshot interval, HTTP timeout, batch limits, dispatch thresholds, statistic chunk size, and per-tick statistic budget are configurable.
+- [x] Blank required values, non-positive limits, overlong server names, invalid UUIDs, and statistic chunks without sufficient batch headroom prevent initialization.
+- [x] Initialization errors are logged and leave the plugin disabled rather than partially running.
+
+## Related
+
+- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+- [US-005: Deliver events durably](us-005-deliver-events-durably.md)
+- [Configuration reference](../../README.md#configuration)

design/user-stories/us-002-produce-standard-cloud-events.md

@@ -0,0 +1,25 @@
+---
+type: User Story
+title: "US-002: Produce standard CloudEvents"
+description: Represent captured Minecraft activity as consistently identifiable CloudEvents 1.0 records.
+status: done
+---
+
+# US-002: Produce standard CloudEvents
+
+As an **event consumer**, I want Minecraft activity represented by a consistent CloudEvents envelope so that I can process records from multiple servers and players reliably.
+
+## Acceptance criteria
+
+- [x] Every record is a structured CloudEvents 1.0 JSON object with a unique stable event ID, UTC time, source, type, and JSON content type.
+- [x] Event types use the `games.dmg.minecraft.*` namespace.
+- [x] Every event includes the stable server ID, server name, and game version as extensions and in its data.
+- [x] Player events include the player UUID as an extension and include the player UUID and current name in their data.
+- [x] An event retains the same ID and payload while it is retried from the outbox.
+
+## Related
+
+- [US-001: Configure the event producer](us-001-configure-event-producer.md)
+- [US-003: Capture player and server activity](us-003-capture-player-activity.md)
+- [US-004: Capture periodic player snapshots](us-004-capture-player-snapshots.md)
+- [Event reference](../../README.md#events)

design/user-stories/us-003-capture-player-activity.md

@@ -0,0 +1,26 @@
+---
+type: User Story
+title: "US-003: Capture player and server activity"
+description: Record server lifecycle, player sessions, public chat, and recognized private messages.
+status: done
+---
+
+# US-003: Capture player and server activity
+
+As a **server analyst**, I want significant server and player activity captured so that I can reconstruct participation and communication activity downstream.
+
+## Acceptance criteria
+
+- [x] Plugin startup and shutdown produce server lifecycle events.
+- [x] Player joins and quits produce events with player identity.
+- [x] Non-cancelled public chat produces an event containing the complete message and whether the Bukkit event was asynchronous.
+- [x] Recognized explicit private-message commands capture the command, recipient token, and complete message.
+- [x] Recognized reply commands are marked as replies and omit a recipient.
+- [x] Private-message observations report whether the underlying command was cancelled.
+- [x] Standard aliases and namespaced variants documented by the project are recognized.
+
+## Related
+
+- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+- [US-005: Deliver events durably](us-005-deliver-events-durably.md)
+- [Chat and private-message behavior](../../README.md#chat-and-private-messages)

design/user-stories/us-004-capture-player-snapshots.md

@@ -0,0 +1,27 @@
+---
+type: User Story
+title: "US-004: Capture periodic player snapshots"
+description: Periodically capture player location and comprehensive Bukkit statistics without monopolizing a server tick.
+status: done
+---
+
+# US-004: Capture periodic player snapshots
+
+As a **server analyst**, I want periodic player location and statistic snapshots so that I can analyze movement and gameplay progression over time.
+
+## Acceptance criteria
+
+- [x] Each configured interval captures every online player's world identity, coordinates, orientation, game mode, and biome.
+- [x] Every Bukkit untyped, block, item, and entity statistic combination accepted by Bukkit is captured, including zero values.
+- [x] Invalid statistic subtype combinations are skipped without stopping the snapshot.
+- [x] Statistic reads are spread across ticks according to a configurable operation budget and run through Bukkit scheduling.
+- [x] A player is not queued for a second statistic capture while an earlier capture remains queued or active.
+- [x] Statistics are partitioned by category and configured JSON size, with shared snapshot metadata and one-based part information.
+- [x] Empty statistic categories still emit an explicit part.
+- [x] Offline players are removed safely from queued or active capture work.
+
+## Related
+
+- [US-001: Configure the event producer](us-001-configure-event-producer.md)
+- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+- [Snapshot behavior](../../README.md#location-snapshots)

design/user-stories/us-005-deliver-events-durably.md

@@ -0,0 +1,27 @@
+---
+type: User Story
+title: "US-005: Deliver events durably"
+description: Persist events locally and deliver ordered, bounded batches without blocking the Minecraft server thread.
+status: done
+---
+
+# US-005: Deliver events durably
+
+As a **server operator**, I want captured events buffered durably and retried after ingest failures so that temporary outages do not silently lose activity.
+
+## Acceptance criteria
+
+- [x] Events are persisted in an ordered local SQLite outbox before delivery.
+- [x] Persistence and HTTP delivery use dedicated workers rather than performing SQLite or network work on the Bukkit server thread.
+- [x] Delivery uses newline-delimited JSON batches bounded by configured event and byte limits.
+- [x] Delivery is requested periodically and may also be requested when an event-count or byte threshold is reached.
+- [x] Events are acknowledged and removed only after the ingest endpoint returns HTTP `202 Accepted`.
+- [x] Failed deliveries remain in the outbox and are retried with bounded exponential backoff.
+- [x] Stable event IDs provide at-least-once delivery semantics suitable for downstream deduplication.
+- [x] Shutdown waits for the shutdown event to be persisted and drains pending persistence work before closing the outbox.
+
+## Related
+
+- [US-001: Configure the event producer](us-001-configure-event-producer.md)
+- [US-002: Produce standard CloudEvents](us-002-produce-standard-cloud-events.md)
+- [Delivery and durability](../../README.md#delivery-and-durability)

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

@@ -0,0 +1,25 @@
+---
+type: User Story
+title: "US-006: Build and release the plugin"
+description: Give maintainers repeatable Java builds, automated verification, and versioned Gitea releases.
+status: done
+---
+
+# US-006: Build and release the plugin
+
+As a **plugin maintainer**, I want automated builds and releases so that tested, correctly versioned plugin artifacts can be distributed consistently.
+
+## Acceptance criteria
+
+- [x] The Gradle project compiles against Java 17 and the supported Spigot API.
+- [x] Automated 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.
+
+## Related
+
+- [Build and release documentation](../../README.md#releases)
+- [User-story catalog](index.md)