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

.gitea/workflows/ci.yml

@@ -32,15 +32,9 @@ jobs:
       - name: Build and test
         run: ./gradlew clean check jar
 
-      - name: Name development artifact
-        run: |
-          short_sha=$(printf '%s' "$GITHUB_SHA" | cut -c1-7)
-          cp build/libs/spigot-event-producer-0.1.0-SNAPSHOT.jar \
-            "build/libs/spigot-event-producer-dev-${short_sha}.jar"
-
       - name: Upload development artifact
         uses: actions/upload-artifact@v3
         with:
           name: spigot-event-producer-${{ github.sha }}
-          path: build/libs/spigot-event-producer-dev-*.jar
+          path: build/libs/*.jar
           if-no-files-found: error

.gitea/workflows/release.yml

@@ -46,9 +46,9 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
         run: |
           npx -y \
-            -p semantic-release \
+            -p semantic-release@24.2.9 \
-            -p @semantic-release/commit-analyzer \
+            -p @semantic-release/commit-analyzer@13.0.1 \
-            -p @semantic-release/release-notes-generator \
+            -p @semantic-release/release-notes-generator@14.1.0 \
             semantic-release \
             --branches main \
             --plugins @semantic-release/commit-analyzer,@semantic-release/release-notes-generator

AGENTS.md

@@ -0,0 +1,9 @@
+# spigot-event-producer agent entrypoint
+
+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).
+
+Before work, read the sibling `../somc-okf/index.md`, `../somc-okf/processes/index.md`, `../somc-okf/projects/spigot-event-producer/index.md`, `engineering.md` in that project section, and relevant `../somc-okf/user-stories/spigot-event-producer/` stories. Also follow the parent workspace `AGENTS.md` when present.
+
+For standalone checkouts, start at the [project page](https://git.garvis.dev/dmg/somc-okf/src/branch/main/projects/spigot-event-producer/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.
+
+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.

src/main/java/games/dmg/spigotevents/stats/BukkitRegistryKeys.java

@@ -0,0 +1,21 @@
+package games.dmg.spigotevents.stats;
+
+import org.bukkit.Keyed;
+import org.bukkit.NamespacedKey;
+
+final class BukkitRegistryKeys {
+    private BukkitRegistryKeys() {}
+
+    static NamespacedKey get(Keyed value) {
+        try {
+            return value.getKey();
+        } catch (IllegalArgumentException ignored) {
+            return null;
+        }
+    }
+
+    static String format(Keyed value, String fallback) {
+        NamespacedKey key = get(value);
+        return key == null ? fallback : key.toString();
+    }
+}

src/main/java/games/dmg/spigotevents/stats/PlayerSnapshotCollector.java

@@ -44,8 +44,7 @@ public final class PlayerSnapshotCollector {
         data.put("pitch", location.getPitch());
         data.put("game_mode", player.getGameMode().name().toLowerCase());
         var biome = location.getBlock().getBiome();
-        var biomeKey = biome.getKeyOrNull();
+        data.put("biome", BukkitRegistryKeys.format(biome, biome.toString()));
-        data.put("biome", biomeKey == null ? biome.toString() : biomeKey.toString());
         publish("player.location", identity(player), data);
     }
 
@@ -157,9 +156,13 @@ public final class PlayerSnapshotCollector {
                 if ((blocksOnly && !material.isBlock()) || (!blocksOnly && !material.isItem())) {
                     continue;
                 }
+                var materialKey = BukkitRegistryKeys.get(material);
+                if (materialKey == null) {
+                    continue;
+                }
                 try {
                     target.put(
-                            statistic.getKey() + "/" + material.getKeyOrThrow(),
+                            statistic.getKey() + "/" + materialKey,
                             currentPlayer.getStatistic(statistic, material));
                 } catch (IllegalArgumentException ignored) {
                     // Bukkit rejects combinations not represented by the game.
@@ -180,9 +183,13 @@ public final class PlayerSnapshotCollector {
             while (operations < budget && subtypeIndex < ENTITY_TYPES.length) {
                 EntityType entityType = ENTITY_TYPES[subtypeIndex++];
                 operations++;
+                var entityTypeKey = BukkitRegistryKeys.get(entityType);
+                if (entityTypeKey == null) {
+                    continue;
+                }
                 try {
                     target.put(
-                            statistic.getKey() + "/" + entityType.getKeyOrThrow(),
+                            statistic.getKey() + "/" + entityTypeKey,
                             currentPlayer.getStatistic(statistic, entityType));
                 } catch (IllegalArgumentException ignored) {
                     // Bukkit rejects unsupported entity types.

src/test/java/games/dmg/spigotevents/stats/BukkitRegistryKeysTest.java

@@ -0,0 +1,33 @@
+package games.dmg.spigotevents.stats;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import org.bukkit.NamespacedKey;
+import org.bukkit.Keyed;
+import org.junit.jupiter.api.Test;
+
+class BukkitRegistryKeysTest {
+    @Test
+    void formatsARegisteredKey() {
+        Keyed keyed = () -> NamespacedKey.minecraft("plains");
+
+        assertEquals("minecraft:plains", BukkitRegistryKeys.format(keyed, "fallback"));
+    }
+
+    @Test
+    void reportsAnUnavailableKey() {
+        Keyed keyed = () -> null;
+
+        assertNull(BukkitRegistryKeys.get(keyed));
+    }
+
+    @Test
+    void reportsAKeyThatBukkitRejectsAsUnavailable() {
+        Keyed keyed = () -> {
+            throw new IllegalArgumentException("Registry entry does not have a key");
+        };
+
+        assertNull(BukkitRegistryKeys.get(keyed));
+    }
+}