v1.3.1: NBT preservation, GUI previews, and global placement toggle

oyeOwner/INTEGRATION_GUIDE.md

@@ -0,0 +1,57 @@
+# oyeOwner Integration Guide for AI Assistants
+
+This document provides concise instructions for integrating the **oyeOwner** API into other Bukkit/Spigot plugins.
+
+## 1. Dependency Configuration (Maven)
+Add the `oyeOwner` project as a dependency in your `pom.xml`.
+
+```xml
+<dependency>
+    <groupId>party.cybsec</groupId>
+    <artifactId>oyeOwner</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <scope>provided</scope>
+</dependency>
+```
+
+## 2. Plugin Configuration (plugin.yml)
+Add `oyeOwner` as a dependency to ensure it loads before your plugin.
+
+```yaml
+depend: [oyeOwner]
+```
+
+## 3. Java API Usage
+
+### Accessing the API
+The API is accessible via a static getter in the main class: `party.cybsec.OyeOwner.getAPI()`.
+
+### Sync Lookup (Blocking)
+Use this if you are already in an asynchronous task or if a tiny delay is acceptable.
+```java
+import org.bukkit.block.Block;
+import party.cybsec.OyeOwner;
+
+// Returns String username or null
+String owner = OyeOwner.getAPI().getBlockOwner(block);
+```
+
+### Async Lookup (Non-blocking)
+Recommended for use on the main thread to avoid lag.
+```java
+import org.bukkit.block.Block;
+import party.cybsec.OyeOwner;
+
+OyeOwner.getAPI().getBlockOwnerAsync(block).thenAccept(owner -> {
+    if (owner != null) {
+        // Player name found: owner
+    } else {
+        // No ownership data found
+    }
+});
+```
+
+## 4. Summary of Capabilities
+- **Lookback Period**: 60 days.
+- **Action Tracked**: Block Placement (Action ID 1).
+- **Core Engine**: Powered by CoreProtect with a reflection-based safe hook.