feat(atproto): implement identity linking, auth, and command system

Add core AT Protocol integration with Slingshot-based PDS resolution,
player identity linking, authenticated sessions, and in-game commands.
Includes session persistence, token refresh, and expanded documentation.

README.md

···
 
 ## ⚠️ Project Status
 
-**This project is in early planning stages and is NOT ready for production use.** The current repository contains a Fabric mod template to establish the initial project structure. Active development and implementation are ongoing.
+**This project is in active development and is NOT ready for production use.** Identity linking and authentication are now implemented, but stat syncing and other features are still in progress.
 
 ## Overview
 
 atproto-connect aims to integrate Minecraft gameplay with the AT Protocol (the protocol powering Bluesky), allowing game data to be synced to AT Protocol lexicons. This enables decentralized storage and sharing of Minecraft data across the federated network.
 
-## Goals
+## Current Features
+
+### Identity Linking & Authentication ✓
+
+Players can link their Minecraft accounts to their AT Protocol identities and authenticate to enable data syncing:
+
+**Basic Commands:**
+
+- **`/atproto link <handle or DID>`** - Link your Minecraft UUID to your AT Protocol identity (no login required)
+- **`/atproto login <handle> <app-password>`** - Authenticate to enable data syncing
+- **`/atproto logout`** - Remove authentication (keeps identity link)
+- **`/atproto unlink`** - Remove identity link and authentication
+- **`/atproto whoami`** - View your linked identity and auth status
+- **`/atproto status`** - Quick status check
+- **`/atproto whois <player or handle>`** - Look up another player's identity
+
+**Example Workflow:**
 
-- **Decentralized Data Sync**: Publish Minecraft gameplay data to AT Protocol repositories
-- **Cross-Server Statistics**: Enable player statistics to persist across different servers via AT Protocol
-- **Social Integration**: Connect Minecraft achievements and activities with the broader AT Protocol ecosystem
-- **Lexicon-Based Storage**: Utilize AT Protocol's schema system for structured game data
+```plaintext
+# 1. Link your identity (read-only)
+/atproto link alice.bsky.social
+✓ Successfully linked to AT Protocol!
+  Handle: alice.bsky.social
+  DID: did:plc:abcdef123456
+  PDS: https://morel.us-east.host.bsky.network
 
-## Use Cases
+# 2. Authenticate with an App Password
+/atproto login alice.bsky.social abcd-1234-efgh-5678
+✓ Successfully authenticated!
+You can now sync your Minecraft data to AT Protocol!
 
-### Player Statistics & Leaderboards
+# 3. Check your status
+/atproto whoami
+━━━ Your AT Protocol Identity ━━━
+Handle: alice.bsky.social
+DID: did:plc:abcdef123456
+Linked: 5 minutes ago
+Last Verified: 5 minutes ago
 
-Sync player statistics (blocks mined, mobs killed, distance traveled, etc.) to AT Protocol lexicons, enabling:
+Authentication: ✓ Active
+You can sync data to AT Protocol
+```
 
-- Global leaderboards that work across multiple servers
-- Historical stat tracking independent of individual server databases
-- Player achievement portfolios visible on AT Protocol clients
+### Key Features
+
+- **Slingshot Integration**: Uses [Slingshot by Microcosm](https://slingshot.microcosm.blue) for fast, cached PDS resolution
+- **App Password Support**: Secure authentication using AT Protocol app passwords (never use your main password!)
+- **Automatic Token Refresh**: Access tokens are automatically refreshed before expiration
+- **Multi-PDS Support**: Works with any AT Protocol PDS, not just Bluesky
+- **Persistent Sessions**: Authentication survives server restarts
+
+### Getting an App Password
+
+1. Go to your AT Protocol account settings (e.g., Bluesky Settings → Privacy and Security → App Passwords)
+2. Create a new app password with a descriptive name (e.g., "Minecraft Server")
+3. Copy it immediately (you won't see it again!)
+4. Use it in `/atproto login`
+5. **Never share your app password or use your main account password!**
 
 ### Future Possibilities
 
-- Server announcements via AT Protocol feeds
+- Automatic stat syncing at configurable intervals
+- Achievement announcements via AT Protocol feeds
 - Cross-server player reputation systems
-- Decentralized mod/plugin distribution
+- Privacy controls for what data gets synced
 - In-game social features tied to AT Protocol identities
 
 ## Technical Stack
···
 - **Mod Loader**: Fabric API
 - **Protocol**: AT Protocol (atproto)
 - **Language**: Kotlin (with Java interop)
+- **Dependencies**:
+
+  - fabric-language-kotlin 1.13.8+kotlin.2.3.0
+  - kotlinx-serialization for JSON handling
+  - kotlinx-coroutines for async operations
+
+- **Identity Resolution**: [Slingshot](https://slingshot.microcosm.blue) by Microcosm
+- **Authentication**: AT Protocol OAuth/App Passwords
 
 ## Installation
 
 ### For Users
 
-*Installation instructions will be added once the mod reaches a usable state.*
+1. Install [Fabric Loader](https://fabricmc.net/use/) for Minecraft 1.21.10
+2. Download and install [Fabric API](https://modrinth.com/mod/fabric-api)
+3. Download and install [Fabric Language Kotlin](https://modrinth.com/mod/fabric-language-kotlin)
+4. Place the atproto-connect JAR in your `mods` folder
+5. Launch the game and use `/atproto help` to see available commands
 
 ### For Developers
 
···
 ./gradlew build
 ```
 
-## Development Roadmap
+The built JAR will be in `build/libs/`.
+
+## Project Structure
+
+```plaintext
+src/main/
+├── kotlin/com/jollywhoppers/
+│   ├── Atprotoconnect.kt                    # Main mod initializer
+│   └── atproto/
+│       ├── AtProtoClient.kt                 # HTTP client with Slingshot integration
+│       ├── AtProtoSessionManager.kt         # Authentication & token management
+│       ├── AtProtoCommands.kt               # Command handlers
+│       └── PlayerIdentityStore.kt           # UUID<->DID mapping storage
+└── resources/
+    ├── fabric.mod.json                      # Mod metadata
+    └── lexicons/                            # Lexicon schemas
+        ├── com.jollywhoppers.minecraft.defs.json
+        ├── com.jollywhoppers.minecraft.player.profile.json
+        ├── com.jollywhoppers.minecraft.player.stats.json
+        ├── com.jollywhoppers.minecraft.player.session.json
+        ├── com.jollywhoppers.minecraft.achievement.json
+        ├── com.jollywhoppers.minecraft.leaderboard.json
+        └── com.jollywhoppers.minecraft.server.status.json
+```
+
+## Lexicon Schemas
+
+The mod defines several AT Protocol lexicon schemas under the `com.jollywhoppers.minecraft.*` namespace:
+
+- **Player Profile** - Links Minecraft UUIDs to AT Protocol DIDs
+- **Player Stats** - Snapshots of player statistics for leaderboards
+- **Player Sessions** - Play session tracking (join/leave times)
+- **Achievements** - Records of earned achievements/advancements
+- **Leaderboards** - Pre-computed leaderboard entries
+- **Server Status** - Server information and status
 
-- [ ] Design lexicon schemas for Minecraft data types
-- [ ] Implement AT Protocol client integration
-- [ ] Create configuration system for AT Protocol credentials
-- [ ] Build data collection hooks for player statistics
-- [ ] Develop sync engine for pushing data to AT Protocol
-- [ ] Add privacy controls and data filtering options
-- [ ] Create example lexicons and test environments
-- [ ] Write comprehensive documentation
+See `src/main/resources/lexicons/README.md` for detailed schema documentation.
 
-## Architecture (Planned)
+## Architecture
 
 ```plaintext
-Minecraft Server (Fabric)
+Player Commands (/atproto login, /atproto link, etc.)
+    ↓
+AtProtoCommands (Kotlin Coroutines)
     ↓
-atproto-connect Mod
+┌────────────────────────────────────────┐
+│    AtProtoSessionManager               │
+│    (Authentication & Token Storage)     │
+└────────────────────────────────────────┘
+    ↓
+┌────────────────────────────────────────┐
+│         AtProtoClient                  │
+│    (HTTP + XRPC + Slingshot)          │
+└────────────────────────────────────────┘
     ↓
-AT Protocol Client Library
+┌────────────────────────────────────────┐
+│    Slingshot (Microcosm Blue)         │
+│    Fast PDS Resolution & Caching       │
+└────────────────────────────────────────┘
     ↓
-AT Protocol PDS (Personal Data Server)
+AT Protocol Network
+    - Player's PDS (Data & Auth)
+    - plc.directory (DID Resolution)
     ↓
-Federated AT Protocol Network
+Local Storage
+    - player-identities.json (UUID↔DID mappings)
+    - player-sessions.json (Auth tokens)
 ```
 
+## Authentication & Security
+
+### How It Works
+
+1. **Link Identity**: Players link their Minecraft UUID to their AT Protocol DID (read-only, no login required)
+2. **Authenticate**: Players log in with their handle and an app password to create an authenticated session
+3. **Token Management**: The mod stores JWT access and refresh tokens securely
+4. **Auto-Refresh**: Access tokens are automatically refreshed before expiration
+5. **Data Syncing**: Authenticated players can sync their Minecraft data to their PDS
+
+### Security Best Practices
+
+- ✅ **Always use App Passwords**, never main account passwords
+- ✅ Create a unique app password for each Minecraft server
+- ✅ Revoke unused app passwords regularly
+- ✅ Server operators should secure the `config/atproto-connect/` directory
+- ✅ Tokens are stored in JSON files - protect file permissions appropriately
+
+### Token Storage
+
+- **Location**: `config/atproto-connect/player-sessions.json`
+- **Contents**: Access and refresh JWTs for authenticated players
+- **Security**: File permissions should restrict access to server owner only
+- **Lifetime**: Access tokens expire after ~2 hours, refresh tokens last longer
+
+## Development Roadmap
+
+- [x] Design lexicon schemas for Minecraft data types
+- [x] Implement AT Protocol client with Slingshot integration
+- [x] Create identity linking system
+- [x] Implement authentication with app passwords
+- [x] Build session management with automatic token refresh
+- [ ] Add authenticated record creation (writing stats)
+- [ ] Build data collection hooks for player statistics
+- [ ] Implement automatic stat syncing
+- [ ] Add privacy controls and data filtering options
+- [ ] Create example AppView for displaying Minecraft data
+- [ ] Write comprehensive documentation
+- [ ] Add automated tests
+
 ## Contributing
 
-As this project is in early development, contribution guidelines will be established once the core architecture is defined. If you're interested in contributing, please open an issue to discuss your ideas.
+This project is in active development. If you're interested in contributing:
 
-## AT Protocol Resources
+1. Check the Issues page for open tasks
+2. Fork the repository
+3. Create a feature branch
+4. Submit a pull request with a clear description
+
+## Resources
+
+### AT Protocol
 
 - [AT Protocol Documentation](https://atproto.com/)
 - [Lexicon Specifications](https://atproto.com/specs/lexicon)
-- [AT Protocol SDKs](https://atproto.com/sdks)
+- [XRPC API Reference](https://atproto.com/specs/xrpc)
+- [OAuth Specification](https://atproto.com/specs/oauth)
+- [Bluesky API Docs](https://docs.bsky.app/)
+
+### Microcosm
+
+- [Slingshot Documentation](https://slingshot.microcosm.blue/)
+- [Microcosm Project](https://microcosm.blue/)
 
 ## License
 
-License information to be added.
+TBD
 
 ## Disclaimer
 
 This is an experimental project exploring the intersection of decentralized protocols and gaming. It is not affiliated with or endorsed by Mojang, Microsoft, or the official AT Protocol team.
+
+## Acknowledgments
+
+- [Microcosm](https://microcosm.blue) for Slingshot, which makes PDS resolution fast and reliable
+- The AT Protocol team for building an open, decentralized social network protocol
+- The Fabric community for excellent mod development tools
 
 ---
 

src/main/kotlin/com/jollywhoppers/Atprotoconnect.kt

···
 package com.jollywhoppers
 
+import com.jollywhoppers.atproto.AtProtoClient
+import com.jollywhoppers.atproto.AtProtoCommands
+import com.jollywhoppers.atproto.AtProtoSessionManager
+import com.jollywhoppers.atproto.PlayerIdentityStore
 import net.fabricmc.api.ModInitializer
+import net.fabricmc.fabric.api.command.v2.CommandRegistrationCallback
+import net.fabricmc.loader.api.FabricLoader
 import org.slf4j.LoggerFactory
 
 object Atprotoconnect : ModInitializer {
     private val logger = LoggerFactory.getLogger("atproto-connect")
+    private const val MOD_ID = "atproto-connect"
 
-	override fun onInitialize() {
-		// This code runs as soon as Minecraft is in a mod-load-ready state.
-		// However, some things (like resources) may still be uninitialized.
-		// Proceed with mild caution.
-		logger.info("Hello Fabric world!")
-	}
-}
+    // AT Protocol components
+    lateinit var atProtoClient: AtProtoClient
+        private set
+    
+    lateinit var identityStore: PlayerIdentityStore
+        private set
+    
+    lateinit var sessionManager: AtProtoSessionManager
+        private set
+    
+    lateinit var commands: AtProtoCommands
+        private set
+
+    override fun onInitialize() {
+        logger.info("Initializing atproto-connect mod")
+
+        try {
+            // Initialize AT Protocol client with Slingshot for PDS resolution
+            atProtoClient = AtProtoClient(
+                slingshotUrl = "https://slingshot.microcosm.blue",
+                fallbackPdsUrl = "https://bsky.social"
+            )
+            logger.info("AT Protocol client initialized with Slingshot resolver")
+
+            // Initialize identity store
+            val configDir = FabricLoader.getInstance().configDir
+            val identityStorePath = configDir.resolve("$MOD_ID/player-identities.json")
+            identityStore = PlayerIdentityStore(identityStorePath)
+            logger.info("Player identity store initialized at: $identityStorePath")
+
+            // Initialize session manager
+            val sessionStorePath = configDir.resolve("$MOD_ID/player-sessions.json")
+            sessionManager = AtProtoSessionManager(sessionStorePath, atProtoClient)
+            logger.info("Session manager initialized at: $sessionStorePath")
+
+            // Initialize command handler
+            commands = AtProtoCommands(atProtoClient, identityStore, sessionManager)
+
+            // Register commands
+            CommandRegistrationCallback.EVENT.register { dispatcher, _, _ ->
+                commands.register(dispatcher)
+                logger.info("AT Protocol commands registered")
+            }
+
+            logger.info("atproto-connect mod successfully initialized!")
+            logger.info("Players can use /atproto help to see available commands")
+        } catch (e: Exception) {
+            logger.error("Failed to initialize atproto-connect mod", e)
+        }
+    }
+
+    /**
+     * Gets the mod version from the metadata.
+     */
+    fun getVersion(): String {
+        return FabricLoader.getInstance()
+            .getModContainer(MOD_ID)
+            .map { it.metadata.version.friendlyString }
+            .orElse("unknown")
+    }
+}

src/main/kotlin/com/jollywhoppers/atproto/AtProtoClient.kt

···
+package com.jollywhoppers.atproto
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import org.slf4j.LoggerFactory
+import java.net.URI
+import java.net.http.HttpClient
+import java.net.http.HttpRequest
+import java.net.http.HttpResponse
+import java.time.Duration
+import java.util.*
+
+/**
+ * Enhanced AT Protocol client with PDS resolution via Slingshot.
+ * Handles identity resolution, authentication, and XRPC requests.
+ */
+class AtProtoClient(
+    private val slingshotUrl: String = "https://slingshot.microcosm.blue",
+    private val fallbackPdsUrl: String = "https://bsky.social"
+) {
+    private val logger = LoggerFactory.getLogger("atproto-connect")
+    private val httpClient = HttpClient.newBuilder()
+        .connectTimeout(Duration.ofSeconds(10))
+        .followRedirects(HttpClient.Redirect.NORMAL)
+        .build()
+    
+    private val json = Json {
+        ignoreUnknownKeys = true
+        isLenient = true
+        prettyPrint = false
+    }
+
+    @Serializable
+    data class MiniDoc(
+        val did: String,
+        val handle: String,
+        val pds: String,
+        val pdsKnown: Boolean = false
+    )
+
+    @Serializable
+    data class DidDocument(
+        val id: String,
+        val alsoKnownAs: List<String> = emptyList(),
+        val verificationMethod: List<VerificationMethod> = emptyList(),
+        val service: List<Service> = emptyList()
+    )
+
+    @Serializable
+    data class VerificationMethod(
+        val id: String,
+        val type: String,
+        val controller: String,
+        val publicKeyMultibase: String? = null
+    )
+
+    @Serializable
+    data class Service(
+        val id: String,
+        val type: String,
+        val serviceEndpoint: String
+    )
+
+    @Serializable
+    data class HandleResolution(
+        val did: String
+    )
+
+    @Serializable
+    data class ProfileView(
+        val did: String,
+        val handle: String,
+        val displayName: String? = null,
+        val description: String? = null,
+        val avatar: String? = null
+    )
+
+    @Serializable
+    data class CreateSessionRequest(
+        val identifier: String,
+        val password: String
+    )
+
+    @Serializable
+    data class CreateSessionResponse(
+        val did: String,
+        val handle: String,
+        val email: String? = null,
+        val accessJwt: String,
+        val refreshJwt: String,
+        val didDoc: DidDocument? = null
+    )
+
+    @Serializable
+    data class RefreshSessionRequest(
+        val refreshJwt: String
+    )
+
+    /**
+     * Resolves an identifier (handle or DID) to a MiniDoc using Slingshot.
+     * This is the preferred method as it's fast and cached.
+     */
+    suspend fun resolveMiniDoc(identifier: String): Result<MiniDoc> = runCatching {
+        logger.info("Resolving identifier via Slingshot: $identifier")
+        
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create("$slingshotUrl/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=${encodeURIComponent(identifier)}"))
+            .GET()
+            .timeout(Duration.ofSeconds(10))
+            .build()
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() != 200) {
+            throw Exception("Failed to resolve via Slingshot: HTTP ${response.statusCode()}")
+        }
+
+        val miniDoc = json.decodeFromString<MiniDoc>(response.body())
+        logger.info("Resolved ${miniDoc.handle} -> PDS: ${miniDoc.pds}")
+        miniDoc
+    }
+
+    /**
+     * Resolves an AT Protocol handle to a DID.
+     * Falls back to standard resolution if Slingshot fails.
+     */
+    suspend fun resolveHandle(handle: String): Result<String> = runCatching {
+        logger.info("Resolving handle: $handle")
+        
+        // Try Slingshot's MiniDoc first
+        try {
+            val miniDoc = resolveMiniDoc(handle).getOrThrow()
+            return@runCatching miniDoc.did
+        } catch (e: Exception) {
+            logger.warn("Slingshot resolution failed, trying fallback: ${e.message}")
+        }
+
+        // Fallback to standard XRPC resolution
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create("$fallbackPdsUrl/xrpc/com.atproto.identity.resolveHandle?handle=$handle"))
+            .GET()
+            .timeout(Duration.ofSeconds(10))
+            .build()
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() != 200) {
+            throw Exception("Failed to resolve handle: HTTP ${response.statusCode()}")
+        }
+
+        val resolution = json.decodeFromString<HandleResolution>(response.body())
+        logger.info("Resolved handle $handle to DID: ${resolution.did}")
+        resolution.did
+    }
+
+    /**
+     * Resolves a DID to its DID Document.
+     * Supports did:plc and did:web methods.
+     */
+    suspend fun resolveDid(did: String): Result<DidDocument> = runCatching {
+        logger.info("Resolving DID: $did")
+        
+        val url = when {
+            did.startsWith("did:plc:") -> {
+                val identifier = did.removePrefix("did:plc:")
+                "https://plc.directory/$identifier"
+            }
+            did.startsWith("did:web:") -> {
+                val domain = did.removePrefix("did:web:")
+                "https://$domain/.well-known/did.json"
+            }
+            else -> throw IllegalArgumentException("Unsupported DID method: $did")
+        }
+
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create(url))
+            .GET()
+            .timeout(Duration.ofSeconds(10))
+            .build()
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() != 200) {
+            throw Exception("Failed to resolve DID: HTTP ${response.statusCode()}")
+        }
+
+        val didDoc = json.decodeFromString<DidDocument>(response.body())
+        logger.info("Resolved DID $did successfully")
+        didDoc
+    }
+
+    /**
+     * Gets a profile from the AT Protocol network.
+     * Uses Slingshot for PDS resolution if needed.
+     */
+    suspend fun getProfile(actor: String, pdsUrl: String? = null): Result<ProfileView> = runCatching {
+        logger.info("Fetching profile for: $actor")
+        
+        val serviceUrl = pdsUrl ?: run {
+            // Resolve PDS if not provided
+            try {
+                val miniDoc = resolveMiniDoc(actor).getOrThrow()
+                miniDoc.pds
+            } catch (e: Exception) {
+                logger.warn("Could not resolve PDS, using fallback: ${e.message}")
+                fallbackPdsUrl
+            }
+        }
+        
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create("$serviceUrl/xrpc/app.bsky.actor.getProfile?actor=$actor"))
+            .GET()
+            .timeout(Duration.ofSeconds(10))
+            .build()
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() != 200) {
+            throw Exception("Failed to get profile: HTTP ${response.statusCode()}: ${response.body()}")
+        }
+
+        val profile = json.decodeFromString<ProfileView>(response.body())
+        logger.info("Retrieved profile for ${profile.handle} (${profile.did})")
+        profile
+    }
+
+    /**
+     * Creates an authenticated session using identifier and app password.
+     * This is the primary authentication method for the mod.
+     */
+    suspend fun createSession(identifier: String, password: String): Result<CreateSessionResponse> = runCatching {
+        logger.info("Creating session for: $identifier")
+        
+        // Resolve to find the correct PDS
+        val pdsUrl = try {
+            val miniDoc = resolveMiniDoc(identifier).getOrThrow()
+            miniDoc.pds
+        } catch (e: Exception) {
+            logger.warn("Could not resolve PDS via Slingshot, trying fallback: ${e.message}")
+            fallbackPdsUrl
+        }
+        
+        val requestBody = CreateSessionRequest(
+            identifier = identifier,
+            password = password
+        )
+        
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create("$pdsUrl/xrpc/com.atproto.server.createSession"))
+            .POST(HttpRequest.BodyPublishers.ofString(json.encodeToString(CreateSessionRequest.serializer(), requestBody)))
+            .header("Content-Type", "application/json")
+            .timeout(Duration.ofSeconds(15))
+            .build()
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() != 200) {
+            val errorBody = response.body()
+            logger.error("Session creation failed: HTTP ${response.statusCode()}: $errorBody")
+            throw Exception("Failed to create session: HTTP ${response.statusCode()}: $errorBody")
+        }
+
+        val session = json.decodeFromString<CreateSessionResponse>(response.body())
+        logger.info("Session created successfully for ${session.handle}")
+        session
+    }
+
+    /**
+     * Refreshes an existing session using a refresh token.
+     */
+    suspend fun refreshSession(refreshJwt: String, pdsUrl: String): Result<CreateSessionResponse> = runCatching {
+        logger.info("Refreshing session")
+        
+        val requestBody = RefreshSessionRequest(refreshJwt = refreshJwt)
+        
+        val request = HttpRequest.newBuilder()
+            .uri(URI.create("$pdsUrl/xrpc/com.atproto.server.refreshSession"))
+            .POST(HttpRequest.BodyPublishers.ofString(json.encodeToString(RefreshSessionRequest.serializer(), requestBody)))
+            .header("Content-Type", "application/json")
+            .header("Authorization", "Bearer $refreshJwt")
+            .timeout(Duration.ofSeconds(15))
+            .build()
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() != 200) {
+            throw Exception("Failed to refresh session: HTTP ${response.statusCode()}")
+        }
+
+        json.decodeFromString<CreateSessionResponse>(response.body())
+    }
+
+    /**
+     * Makes an authenticated XRPC request.
+     */
+    suspend fun xrpcRequest(
+        method: String,
+        endpoint: String,
+        accessJwt: String,
+        pdsUrl: String,
+        body: String? = null
+    ): Result<String> = runCatching {
+        val requestBuilder = HttpRequest.newBuilder()
+            .uri(URI.create("$pdsUrl/xrpc/$endpoint"))
+            .header("Authorization", "Bearer $accessJwt")
+            .header("Content-Type", "application/json")
+            .timeout(Duration.ofSeconds(15))
+
+        val request = when (method.uppercase()) {
+            "GET" -> requestBuilder.GET().build()
+            "POST" -> requestBuilder.POST(
+                HttpRequest.BodyPublishers.ofString(body ?: "{}")
+            ).build()
+            "PUT" -> requestBuilder.PUT(
+                HttpRequest.BodyPublishers.ofString(body ?: "{}")
+            ).build()
+            "DELETE" -> requestBuilder.DELETE().build()
+            else -> throw IllegalArgumentException("Unsupported HTTP method: $method")
+        }
+
+        val response = httpClient.send(request, HttpResponse.BodyHandlers.ofString())
+        
+        if (response.statusCode() !in 200..299) {
+            throw Exception("XRPC request failed: HTTP ${response.statusCode()}: ${response.body()}")
+        }
+
+        response.body()
+    }
+
+    /**
+     * Validates that a DID is properly formatted.
+     */
+    fun isValidDid(did: String): Boolean {
+        return did.matches(Regex("^did:(plc|web):[a-zA-Z0-9._:%-]+$"))
+    }
+
+    /**
+     * Validates that a handle is properly formatted.
+     */
+    fun isValidHandle(handle: String): Boolean {
+        return handle.matches(Regex("^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$"))
+    }
+
+    /**
+     * Determines if the input is a DID or handle and resolves accordingly.
+     * Returns (DID, handle, PDS URL).
+     */
+    suspend fun resolveIdentifier(identifier: String): Result<Triple<String, String, String>> = runCatching {
+        when {
+            identifier.startsWith("did:") -> {
+                if (!isValidDid(identifier)) {
+                    throw IllegalArgumentException("Invalid DID format")
+                }
+                // Try Slingshot first
+                try {
+                    val miniDoc = resolveMiniDoc(identifier).getOrThrow()
+                    Triple(miniDoc.did, miniDoc.handle, miniDoc.pds)
+                } catch (e: Exception) {
+                    // Fallback to DID resolution
+                    val didDoc = resolveDid(identifier).getOrThrow()
+                    val handle = didDoc.alsoKnownAs.firstOrNull()
+                        ?.removePrefix("at://")
+                        ?: throw Exception("No handle found in DID document")
+                    val pdsService = didDoc.service.firstOrNull { it.type == "AtprotoPersonalDataServer" }
+                        ?: throw Exception("No PDS service found in DID document")
+                    Triple(identifier, handle, pdsService.serviceEndpoint)
+                }
+            }
+            else -> {
+                if (!isValidHandle(identifier)) {
+                    throw IllegalArgumentException("Invalid handle format")
+                }
+                val miniDoc = resolveMiniDoc(identifier).getOrThrow()
+                Triple(miniDoc.did, miniDoc.handle, miniDoc.pds)
+            }
+        }
+    }
+
+    private fun encodeURIComponent(value: String): String {
+        return URI(null, null, null, -1, null, null, null)
+            .resolve(value)
+            .rawSchemeSpecificPart
+            .replace("+", "%20")
+    }
+}

src/main/kotlin/com/jollywhoppers/atproto/AtProtoCommands.kt

···
+package com.jollywhoppers.atproto
+
+import com.mojang.brigadier.CommandDispatcher
+import com.mojang.brigadier.arguments.StringArgumentType
+import com.mojang.brigadier.context.CommandContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import net.minecraft.commands.CommandSourceStack
+import net.minecraft.commands.Commands
+import net.minecraft.network.chat.Component
+import net.minecraft.server.level.ServerPlayer
+import org.slf4j.LoggerFactory
+
+/**
+ * Handles AT Protocol-related commands for players.
+ * Provides commands to link, authenticate, and manage AT Protocol identities.
+ */
+class AtProtoCommands(
+    private val client: AtProtoClient,
+    private val identityStore: PlayerIdentityStore,
+    private val sessionManager: AtProtoSessionManager
+) {
+    private val logger = LoggerFactory.getLogger("atproto-connect")
+    private val coroutineScope = CoroutineScope(Dispatchers.IO)
+
+    /**
+     * Registers all AT Protocol commands.
+     */
+    fun register(dispatcher: CommandDispatcher<CommandSourceStack>) {
+        dispatcher.register(
+            Commands.literal("atproto")
+                .then(
+                    Commands.literal("link")
+                        .then(
+                            Commands.argument("identifier", StringArgumentType.greedyString())
+                                .executes { context -> linkIdentity(context) }
+                        )
+                )
+                .then(
+                    Commands.literal("unlink")
+                        .executes { context -> unlinkIdentity(context) }
+                )
+                .then(
+                    Commands.literal("login")
+                        .then(
+                            Commands.argument("identifier", StringArgumentType.string())
+                                .then(
+                                    Commands.argument("password", StringArgumentType.greedyString())
+                                        .executes { context -> login(context) }
+                                )
+                        )
+                )
+                .then(
+                    Commands.literal("logout")
+                        .executes { context -> logout(context) }
+                )
+                .then(
+                    Commands.literal("whoami")
+                        .executes { context -> whoami(context) }
+                )
+                .then(
+                    Commands.literal("whois")
+                        .then(
+                            Commands.argument("identifier", StringArgumentType.greedyString())
+                                .executes { context -> whois(context) }
+                        )
+                )
+                .then(
+                    Commands.literal("status")
+                        .executes { context -> status(context) }
+                )
+                .executes { context -> help(context) }
+        )
+    }
+
+    /**
+     * Links a player's Minecraft UUID to their AT Protocol identity (without authentication).
+     */
+    private fun linkIdentity(context: CommandContext<CommandSourceStack>): Int {
+        val player = context.source.playerOrException
+        val identifier = StringArgumentType.getString(context, "identifier")
+
+        context.source.sendSuccess(
+            { Component.literal("§eVerifying AT Protocol identity...") },
+            false
+        )
+
+        coroutineScope.launch {
+            try {
+                // Resolve the identifier (handle or DID) to get DID, handle, and PDS
+                val (did, handle, pdsUrl) = client.resolveIdentifier(identifier).getOrThrow()
+
+                // Verify the identity exists by fetching the profile
+                val profile = client.getProfile(did, pdsUrl).getOrThrow()
+
+                // Link the identity
+                identityStore.linkIdentity(player.uuid, profile.did, profile.handle)
+
+                player.sendSystemMessage(
+                    Component.literal("§a✓ Successfully linked to AT Protocol!")
+                        .append(Component.literal("\n§7Handle: §f${profile.handle}"))
+                        .append(Component.literal("\n§7DID: §f${profile.did}"))
+                        .append(Component.literal("\n§7PDS: §f$pdsUrl"))
+                        .apply {
+                            profile.displayName?.let {
+                                append(Component.literal("\n§7Display Name: §f$it"))
+                            }
+                        }
+                        .append(Component.literal("\n\n§eNote: Use §f/atproto login§e to authenticate and sync data"))
+                )
+
+                logger.info("Player ${player.name.string} (${player.uuid}) linked to ${profile.handle}")
+            } catch (e: Exception) {
+                player.sendSystemMessage(
+                    Component.literal("§c✗ Failed to link AT Protocol identity")
+                        .append(Component.literal("\n§7${e.message ?: "Unknown error"}"))
+                )
+                logger.error("Failed to link identity for player ${player.name.string}", e)
+            }
+        }
+
+        return 1
+    }
+
+    /**
+     * Unlinks a player's Minecraft UUID from their AT Protocol identity.
+     */
+    private fun unlinkIdentity(context: CommandContext<CommandSourceStack>): Int {
+        val player = context.source.playerOrException
+        val identity = identityStore.getIdentity(player.uuid)
+
+        return if (identity != null) {
+            // Also logout if they're authenticated
+            if (sessionManager.hasSession(player.uuid)) {
+                sessionManager.deleteSession(player.uuid)
+            }
+            
+            identityStore.unlinkIdentity(player.uuid)
+            context.source.sendSuccess(
+                {
+                    Component.literal("§a✓ Unlinked from AT Protocol identity")
+                        .append(Component.literal("\n§7Previously linked to: §f${identity.handle}"))
+                },
+                false
+            )
+            logger.info("Player ${player.name.string} (${player.uuid}) unlinked from ${identity.handle}")
+            1
+        } else {
+            context.source.sendFailure(
+                Component.literal("§c✗ You don't have a linked AT Protocol identity")
+            )
+            0
+        }
+    }
+
+    /**
+     * Authenticates a player with their AT Protocol credentials.
+     * Uses app passwords for security.
+     */
+    private fun login(context: CommandContext<CommandSourceStack>): Int {
+        val player = context.source.playerOrException
+        val identifier = StringArgumentType.getString(context, "identifier")
+        val password = StringArgumentType.getString(context, "password")
+
+        context.source.sendSuccess(
+            { Component.literal("§eAuthenticating with AT Protocol...") },
+            false
+        )
+
+        coroutineScope.launch {
+            try {
+                // Create session
+                val session = sessionManager.createSession(player.uuid, identifier, password).getOrThrow()
+
+                // Link identity if not already linked
+                if (!identityStore.isLinked(player.uuid)) {
+                    identityStore.linkIdentity(player.uuid, session.did, session.handle)
+                }
+
+                player.sendSystemMessage(
+                    Component.literal("§a✓ Successfully authenticated!")
+                        .append(Component.literal("\n§7Handle: §f${session.handle}"))
+                        .append(Component.literal("\n§7DID: §f${session.did}"))
+                        .append(Component.literal("\n§7PDS: §f${session.pdsUrl}"))
+                        .append(Component.literal("\n\n§aYou can now sync your Minecraft data to AT Protocol!"))
+                )
+
+                logger.info("Player ${player.name.string} (${player.uuid}) authenticated as ${session.handle}")
+            } catch (e: Exception) {
+                player.sendSystemMessage(
+                    Component.literal("§c✗ Authentication failed")
+                        .append(Component.literal("\n§7${e.message ?: "Unknown error"}"))
+                        .append(Component.literal("\n\n§7Tip: Use an §fApp Password§7 from your AT Protocol account settings"))
+                        .append(Component.literal("\n§7Never use your main account password!"))
+                )
+                logger.error("Failed to authenticate player ${player.name.string}", e)
+            }
+        }
+
+        return 1
+    }
+
+    /**
+     * Logs out a player (removes their authentication session).
+     */
+    private fun logout(context: CommandContext<CommandSourceStack>): Int {
+        val player = context.source.playerOrException
+        
+        return if (sessionManager.hasSession(player.uuid)) {
+            sessionManager.deleteSession(player.uuid)
+            context.source.sendSuccess(
+                {
+                    Component.literal("§a✓ Logged out successfully")
+                        .append(Component.literal("\n§7Your identity link remains active"))
+                        .append(Component.literal("\n§7Use §f/atproto login§7 to authenticate again"))
+                },
+                false
+            )
+            logger.info("Player ${player.name.string} (${player.uuid}) logged out")
+            1
+        } else {
+            context.source.sendFailure(
+                Component.literal("§c✗ You are not logged in")
+            )
+            0
+        }
+    }
+
+    /**
+     * Shows the player their own linked AT Protocol identity and authentication status.
+     */
+    private fun whoami(context: CommandContext<CommandSourceStack>): Int {
+        val player = context.source.playerOrException
+        val identity = identityStore.getIdentity(player.uuid)
+
+        return if (identity != null) {
+            val linkedAgo = formatTimeSince(identity.linkedAt)
+            val verifiedAgo = formatTimeSince(identity.lastVerified)
+            val isAuthenticated = sessionManager.hasSession(player.uuid)
+
+            context.source.sendSuccess(
+                {
+                    Component.literal("§b━━━ Your AT Protocol Identity ━━━")
+                        .append(Component.literal("\n§7Handle: §f${identity.handle}"))
+                        .append(Component.literal("\n§7DID: §f${identity.did}"))
+                        .append(Component.literal("\n§7Linked: §f$linkedAgo ago"))
+                        .append(Component.literal("\n§7Last Verified: §f$verifiedAgo ago"))
+                        .append(Component.literal("\n"))
+                        .append(
+                            if (isAuthenticated) {
+                                Component.literal("\n§aAuthentication: §f✓ Active")
+                                    .append(Component.literal("\n§7You can sync data to AT Protocol"))
+                            } else {
+                                Component.literal("\n§cAuthentication: §f✗ Not logged in")
+                                    .append(Component.literal("\n§7Use §f/atproto login§7 to authenticate"))
+                            }
+                        )
+                },
+                false
+            )
+            1
+        } else {
+            context.source.sendFailure(
+                Component.literal("§c✗ You don't have a linked AT Protocol identity")
+                    .append(Component.literal("\n§7Use §f/atproto link <handle or DID>§7 to link your identity"))
+            )
+            0
+        }
+    }
+
+    /**
+     * Shows information about another player's AT Protocol identity.
+     */
+    private fun whois(context: CommandContext<CommandSourceStack>): Int {
+        val identifier = StringArgumentType.getString(context, "identifier")
+
+        coroutineScope.launch {
+            try {
+                val player = context.source.playerOrException
+
+                // Try to find by Minecraft username first
+                val minecraftPlayer = context.source.server.playerList.players
+                    .firstOrNull { it.name.string.equals(identifier, ignoreCase = true) }
+
+                val identity = if (minecraftPlayer != null) {
+                    identityStore.getIdentity(minecraftPlayer.uuid)
+                } else {
+                    // Try as AT Protocol handle or DID
+                    val uuid = identityStore.getUuidByHandle(identifier)
+                        ?: identityStore.getUuidByDid(identifier)
+                    uuid?.let { identityStore.getIdentity(it) }
+                }
+
+                if (identity != null) {
+                    val linkedAgo = formatTimeSince(identity.linkedAt)
+                    player.sendSystemMessage(
+                        Component.literal("§b━━━ AT Protocol Identity ━━━")
+                            .append(Component.literal("\n§7Handle: §f${identity.handle}"))
+                            .append(Component.literal("\n§7DID: §f${identity.did}"))
+                            .append(Component.literal("\n§7Linked: §f$linkedAgo ago"))
+                    )
+                } else {
+                    player.sendSystemMessage(
+                        Component.literal("§c✗ No linked AT Protocol identity found for: $identifier")
+                    )
+                }
+            } catch (e: Exception) {
+                logger.error("Error in whois command", e)
+            }
+        }
+
+        return 1
+    }
+
+    /**
+     * Shows authentication and connection status.
+     */
+    private fun status(context: CommandContext<CommandSourceStack>): Int {
+        val player = context.source.playerOrException
+        val isLinked = identityStore.isLinked(player.uuid)
+        val isAuthenticated = sessionManager.hasSession(player.uuid)
+
+        context.source.sendSuccess(
+            {
+                Component.literal("§b━━━ AT Protocol Status ━━━")
+                    .append(
+                        if (isLinked) {
+                            val identity = identityStore.getIdentity(player.uuid)!!
+                            Component.literal("\n§aIdentity: §f✓ Linked to ${identity.handle}")
+                        } else {
+                            Component.literal("\n§cIdentity: §f✗ Not linked")
+                        }
+                    )
+                    .append(
+                        if (isAuthenticated) {
+                            Component.literal("\n§aAuthentication: §f✓ Active session")
+                        } else {
+                            Component.literal("\n§cAuthentication: §f✗ Not logged in")
+                        }
+                    )
+                    .append(
+                        if (isLinked && isAuthenticated) {
+                            Component.literal("\n\n§aReady to sync Minecraft data to AT Protocol!")
+                        } else if (isLinked) {
+                            Component.literal("\n\n§eUse §f/atproto login§e to authenticate")
+                        } else {
+                            Component.literal("\n\n§eUse §f/atproto link <handle>§e to get started")
+                        }
+                    )
+            },
+            false
+        )
+        return 1
+    }
+
+    /**
+     * Shows help information for AT Protocol commands.
+     */
+    private fun help(context: CommandContext<CommandSourceStack>): Int {
+        context.source.sendSuccess(
+            {
+                Component.literal("§b━━━ AT Protocol Commands ━━━")
+                    .append(Component.literal("\n§f/atproto link <handle or DID>"))
+                    .append(Component.literal("\n  §7Link your Minecraft account to your AT Protocol identity"))
+                    .append(Component.literal("\n  §7Example: §f/atproto link alice.bsky.social"))
+                    .append(Component.literal("\n"))
+                    .append(Component.literal("\n§f/atproto login <handle> <app-password>"))
+                    .append(Component.literal("\n  §7Authenticate to enable data syncing"))
+                    .append(Component.literal("\n  §7§cUse an App Password, not your main password!"))
+                    .append(Component.literal("\n  §7Get one from: Settings → App Passwords"))
+                    .append(Component.literal("\n"))
+                    .append(Component.literal("\n§f/atproto logout"))
+                    .append(Component.literal("\n  §7Log out (removes authentication, keeps identity link)"))
+                    .append(Component.literal("\n"))
+                    .append(Component.literal("\n§f/atproto unlink"))
+                    .append(Component.literal("\n  §7Unlink your AT Protocol identity completely"))
+                    .append(Component.literal("\n"))
+                    .append(Component.literal("\n§f/atproto whoami"))
+                    .append(Component.literal("\n  §7View your linked identity and authentication status"))
+                    .append(Component.literal("\n"))
+                    .append(Component.literal("\n§f/atproto status"))
+                    .append(Component.literal("\n  §7Check connection status"))
+                    .append(Component.literal("\n"))
+                    .append(Component.literal("\n§f/atproto whois <player or handle>"))
+                    .append(Component.literal("\n  §7Look up another player's AT Protocol identity"))
+            },
+            false
+        )
+        return 1
+    }
+
+    /**
+     * Formats a timestamp into a human-readable "time since" string.
+     */
+    private fun formatTimeSince(timestamp: Long): String {
+        val seconds = (System.currentTimeMillis() - timestamp) / 1000
+        return when {
+            seconds < 60 -> "$seconds seconds"
+            seconds < 3600 -> "${seconds / 60} minutes"
+            seconds < 86400 -> "${seconds / 3600} hours"
+            else -> "${seconds / 86400} days"
+        }
+    }
+}

src/main/kotlin/com/jollywhoppers/atproto/AtProtoSessionManager.kt

···
+package com.jollywhoppers.atproto
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.encodeToString
+import org.slf4j.LoggerFactory
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.StandardOpenOption
+import java.util.*
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Manages AT Protocol authentication sessions for players.
+ * Handles token storage, refresh, and session lifecycle.
+ */
+class AtProtoSessionManager(
+    private val storageFile: Path,
+    private val client: AtProtoClient
+) {
+    private val logger = LoggerFactory.getLogger("atproto-connect")
+    private val sessions = ConcurrentHashMap<UUID, PlayerSession>()
+    
+    private val json = Json {
+        prettyPrint = true
+        ignoreUnknownKeys = true
+    }
+
+    @Serializable
+    data class PlayerSession(
+        val uuid: String,
+        val did: String,
+        val handle: String,
+        val pdsUrl: String,
+        val accessJwt: String,
+        val refreshJwt: String,
+        val createdAt: Long = System.currentTimeMillis(),
+        val lastRefreshed: Long = System.currentTimeMillis()
+    )
+
+    @Serializable
+    private data class SessionStorage(
+        val version: Int = 1,
+        val sessions: List<PlayerSession>
+    )
+
+    init {
+        load()
+    }
+
+    /**
+     * Creates or updates a session for a player.
+     */
+    suspend fun createSession(
+        uuid: UUID,
+        identifier: String,
+        password: String
+    ): Result<PlayerSession> = runCatching {
+        logger.info("Creating session for player $uuid with identifier $identifier")
+        
+        // Create the session via AT Protocol
+        val sessionResponse = client.createSession(identifier, password).getOrThrow()
+        
+        // Resolve to get PDS URL
+        val (did, handle, pdsUrl) = client.resolveIdentifier(sessionResponse.did).getOrThrow()
+        
+        val session = PlayerSession(
+            uuid = uuid.toString(),
+            did = did,
+            handle = handle,
+            pdsUrl = pdsUrl,
+            accessJwt = sessionResponse.accessJwt,
+            refreshJwt = sessionResponse.refreshJwt,
+            createdAt = System.currentTimeMillis(),
+            lastRefreshed = System.currentTimeMillis()
+        )
+        
+        sessions[uuid] = session
+        save()
+        
+        logger.info("Session created successfully for $handle")
+        session
+    }
+
+    /**
+     * Gets the active session for a player.
+     * Automatically refreshes if the access token is expired.
+     */
+    suspend fun getSession(uuid: UUID): Result<PlayerSession> = runCatching {
+        val session = sessions[uuid]
+            ?: throw Exception("No session found for player")
+        
+        // Check if session needs refresh (access tokens typically expire after 2 hours)
+        // We'll refresh if it's been more than 1.5 hours to be safe
+        val hoursSinceRefresh = (System.currentTimeMillis() - session.lastRefreshed) / (1000 * 60 * 60)
+        
+        if (hoursSinceRefresh >= 1.5) {
+            logger.info("Session for ${session.handle} needs refresh")
+            return refreshSession(uuid)
+        }
+        
+        session
+    }
+
+    /**
+     * Refreshes a player's session using their refresh token.
+     */
+    suspend fun refreshSession(uuid: UUID): Result<PlayerSession> = runCatching {
+        val oldSession = sessions[uuid]
+            ?: throw Exception("No session found for player")
+        
+        logger.info("Refreshing session for ${oldSession.handle}")
+        
+        val refreshResponse = client.refreshSession(
+            oldSession.refreshJwt,
+            oldSession.pdsUrl
+        ).getOrThrow()
+        
+        val newSession = oldSession.copy(
+            accessJwt = refreshResponse.accessJwt,
+            refreshJwt = refreshResponse.refreshJwt,
+            lastRefreshed = System.currentTimeMillis()
+        )
+        
+        sessions[uuid] = newSession
+        save()
+        
+        logger.info("Session refreshed successfully for ${oldSession.handle}")
+        newSession
+    }
+
+    /**
+     * Removes a player's session (logout).
+     */
+    fun deleteSession(uuid: UUID): Boolean {
+        val removed = sessions.remove(uuid)
+        if (removed != null) {
+            save()
+            logger.info("Session deleted for ${removed.handle}")
+            return true
+        }
+        return false
+    }
+
+    /**
+     * Checks if a player has an active session.
+     */
+    fun hasSession(uuid: UUID): Boolean {
+        return sessions.containsKey(uuid)
+    }
+
+    /**
+     * Gets all active sessions.
+     */
+    fun getAllSessions(): Map<UUID, PlayerSession> {
+        return sessions.toMap()
+    }
+
+    /**
+     * Makes an authenticated XRPC request for a player.
+     * Automatically refreshes the session if needed.
+     */
+    suspend fun makeAuthenticatedRequest(
+        uuid: UUID,
+        method: String,
+        endpoint: String,
+        body: String? = null
+    ): Result<String> = runCatching {
+        val session = getSession(uuid).getOrThrow()
+        
+        client.xrpcRequest(
+            method = method,
+            endpoint = endpoint,
+            accessJwt = session.accessJwt,
+            pdsUrl = session.pdsUrl,
+            body = body
+        ).getOrThrow()
+    }
+
+    /**
+     * Loads sessions from disk.
+     */
+    private fun load() {
+        try {
+            if (Files.exists(storageFile)) {
+                val content = Files.readString(storageFile)
+                val storage = json.decodeFromString<SessionStorage>(content)
+                
+                storage.sessions.forEach { session ->
+                    val uuid = UUID.fromString(session.uuid)
+                    sessions[uuid] = session
+                }
+                
+                logger.info("Loaded ${sessions.size} sessions from disk")
+            } else {
+                logger.info("No existing session storage found, starting fresh")
+            }
+        } catch (e: Exception) {
+            logger.error("Failed to load sessions", e)
+        }
+    }
+
+    /**
+     * Saves sessions to disk.
+     */
+    private fun save() {
+        try {
+            Files.createDirectories(storageFile.parent)
+            
+            val storage = SessionStorage(
+                version = 1,
+                sessions = sessions.values.toList()
+            )
+            
+            val content = json.encodeToString(storage)
+            Files.writeString(
+                storageFile,
+                content,
+                StandardOpenOption.CREATE,
+                StandardOpenOption.TRUNCATE_EXISTING
+            )
+            
+            logger.debug("Saved ${sessions.size} sessions to disk")
+        } catch (e: Exception) {
+            logger.error("Failed to save sessions", e)
+        }
+    }
+}

src/main/kotlin/com/jollywhoppers/atproto/PlayerIdentityStore.kt

···
+package com.jollywhoppers.atproto
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.encodeToString
+import org.slf4j.LoggerFactory
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.StandardOpenOption
+import java.util.*
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Manages the mapping between Minecraft UUIDs and AT Protocol DIDs.
+ * Handles persistence to disk and in-memory caching.
+ */
+class PlayerIdentityStore(private val storageFile: Path) {
+    private val logger = LoggerFactory.getLogger("atproto-connect")
+    private val identities = ConcurrentHashMap<UUID, PlayerIdentity>()
+    
+    private val json = Json {
+        prettyPrint = true
+        ignoreUnknownKeys = true
+    }
+
+    @Serializable
+    data class PlayerIdentity(
+        val uuid: String,
+        val did: String,
+        val handle: String,
+        val linkedAt: Long = System.currentTimeMillis(),
+        val lastVerified: Long = System.currentTimeMillis()
+    )
+
+    @Serializable
+    private data class IdentityStorage(
+        val version: Int = 1,
+        val identities: List<PlayerIdentity>
+    )
+
+    init {
+        load()
+    }
+
+    /**
+     * Links a Minecraft player UUID to an AT Protocol DID.
+     */
+    fun linkIdentity(uuid: UUID, did: String, handle: String): PlayerIdentity {
+        val identity = PlayerIdentity(
+            uuid = uuid.toString(),
+            did = did,
+            handle = handle,
+            linkedAt = System.currentTimeMillis(),
+            lastVerified = System.currentTimeMillis()
+        )
+        
+        identities[uuid] = identity
+        save()
+        
+        logger.info("Linked player $uuid to AT Protocol identity $handle ($did)")
+        return identity
+    }
+
+    /**
+     * Removes the link between a Minecraft player UUID and their AT Protocol DID.
+     */
+    fun unlinkIdentity(uuid: UUID): Boolean {
+        val removed = identities.remove(uuid)
+        if (removed != null) {
+            save()
+            logger.info("Unlinked player $uuid from AT Protocol identity ${removed.handle}")
+            return true
+        }
+        return false
+    }
+
+    /**
+     * Gets the AT Protocol identity for a Minecraft player UUID.
+     */
+    fun getIdentity(uuid: UUID): PlayerIdentity? {
+        return identities[uuid]
+    }
+
+    /**
+     * Gets the Minecraft UUID for an AT Protocol DID.
+     */
+    fun getUuidByDid(did: String): UUID? {
+        return identities.entries
+            .firstOrNull { it.value.did == did }
+            ?.key
+    }
+
+    /**
+     * Gets the Minecraft UUID for an AT Protocol handle.
+     */
+    fun getUuidByHandle(handle: String): UUID? {
+        return identities.entries
+            .firstOrNull { it.value.handle.equals(handle, ignoreCase = true) }
+            ?.key
+    }
+
+    /**
+     * Checks if a Minecraft player UUID is linked to an AT Protocol identity.
+     */
+    fun isLinked(uuid: UUID): Boolean {
+        return identities.containsKey(uuid)
+    }
+
+    /**
+     * Gets all linked identities.
+     */
+    fun getAllIdentities(): Map<UUID, PlayerIdentity> {
+        return identities.toMap()
+    }
+
+    /**
+     * Updates the last verified timestamp for a player's identity.
+     */
+    fun updateVerification(uuid: UUID) {
+        identities[uuid]?.let { identity ->
+            val updated = identity.copy(lastVerified = System.currentTimeMillis())
+            identities[uuid] = updated
+            save()
+        }
+    }
+
+    /**
+     * Loads identities from disk.
+     */
+    private fun load() {
+        try {
+            if (Files.exists(storageFile)) {
+                val content = Files.readString(storageFile)
+                val storage = json.decodeFromString<IdentityStorage>(content)
+                
+                storage.identities.forEach { identity ->
+                    val uuid = UUID.fromString(identity.uuid)
+                    identities[uuid] = identity
+                }
+                
+                logger.info("Loaded ${identities.size} player identities from disk")
+            } else {
+                logger.info("No existing identity storage found, starting fresh")
+            }
+        } catch (e: Exception) {
+            logger.error("Failed to load player identities", e)
+        }
+    }
+
+    /**
+     * Saves identities to disk.
+     */
+    private fun save() {
+        try {
+            Files.createDirectories(storageFile.parent)
+            
+            val storage = IdentityStorage(
+                version = 1,
+                identities = identities.values.toList()
+            )
+            
+            val content = json.encodeToString(storage)
+            Files.writeString(
+                storageFile,
+                content,
+                StandardOpenOption.CREATE,
+                StandardOpenOption.TRUNCATE_EXISTING
+            )
+            
+            logger.debug("Saved ${identities.size} player identities to disk")
+        } catch (e: Exception) {
+            logger.error("Failed to save player identities", e)
+        }
+    }
+}

src/main/kotlin/com/jollywhoppers/atproto/README.md

···
+# AT Protocol Integration
+
+This package contains the core AT Protocol integration for atproto-connect, enabling Minecraft players to link their game accounts to their AT Protocol identities and authenticate to sync data.
+
+## Components
+
+### AtProtoClient.kt
+Enhanced HTTP client for interacting with AT Protocol services. Provides methods for:
+
+- **Slingshot Integration**: Uses [Slingshot](https://slingshot.microcosm.blue) for fast, cached PDS resolution via `resolveMiniDoc`
+- **Handle Resolution**: Convert AT Protocol handles (e.g., `alice.bsky.social`) to DIDs
+- **DID Resolution**: Resolve DIDs to DID Documents (supports `did:plc` and `did:web`)
+- **Profile Retrieval**: Fetch user profiles from the AT Protocol network
+- **Session Management**: Create and refresh authenticated sessions
+- **XRPC Requests**: Make authenticated API calls to PDS instances
+
+The client uses Java's built-in `HttpClient` for HTTP requests and `kotlinx.serialization` for JSON parsing. It automatically falls back to standard resolution methods if Slingshot is unavailable.
+
+### PlayerIdentityStore.kt
+Manages the persistent mapping between Minecraft UUIDs and AT Protocol DIDs. Features:
+
+- **In-Memory Cache**: Uses `ConcurrentHashMap` for fast lookups
+- **Disk Persistence**: Stores identities in JSON format
+- **Bidirectional Lookup**: Find UUID by DID/handle, or DID/handle by UUID
+- **Verification Tracking**: Records when identities were linked and last verified
+
+The storage file is located at `config/atproto-connect/player-identities.json`.
+
+### AtProtoSessionManager.kt
+Manages authenticated AT Protocol sessions for players. Features:
+
+- **Token Storage**: Securely stores access and refresh tokens
+- **Automatic Refresh**: Refreshes access tokens before expiration
+- **Session Lifecycle**: Handles login, logout, and token management
+- **Authenticated Requests**: Provides helper methods for making authenticated XRPC calls
+
+Sessions are stored at `config/atproto-connect/player-sessions.json`.
+
+### AtProtoCommands.kt
+Brigadier command handler providing in-game commands:
+
+#### `/atproto link <handle or DID>`
+Links the player's Minecraft UUID to their AT Protocol identity (no authentication required).
+- Accepts either a handle (`alice.bsky.social`) or DID (`did:plc:...`)
+- Validates the identity exists on the AT Protocol network
+- Resolves PDS URL via Slingshot
+- Stores the mapping for future use
+
+**Example:**
+```
+/atproto link alice.bsky.social
+✓ Successfully linked to AT Protocol!
+  Handle: alice.bsky.social
+  DID: did:plc:abcdef123456
+  PDS: https://morel.us-east.host.bsky.network
+```
+
+#### `/atproto login <handle> <app-password>`
+Authenticates the player to enable data syncing.
+- **IMPORTANT**: Always use an App Password, never your main account password!
+- Creates an authenticated session with the player's PDS
+- Stores access and refresh tokens securely
+- Enables stat syncing and record creation
+
+**Getting an App Password:**
+1. Go to your AT Protocol account settings
+2. Navigate to App Passwords
+3. Create a new app password with a descriptive name (e.g., "Minecraft Server")
+4. Copy the password immediately (you won't see it again!)
+5. Use it in the login command
+
+**Example:**
+```
+/atproto login alice.bsky.social abcd-1234-efgh-5678
+✓ Successfully authenticated!
+  Handle: alice.bsky.social
+  DID: did:plc:abcdef123456
+  PDS: https://morel.us-east.host.bsky.network
+
+You can now sync your Minecraft data to AT Protocol!
+```
+
+#### `/atproto logout`
+Removes the player's authenticated session (but keeps their identity link).
+
+#### `/atproto unlink`
+Removes both the identity link and any authenticated session.
+
+#### `/atproto whoami`
+Displays the player's linked AT Protocol identity and authentication status.
+
+#### `/atproto status`
+Shows a quick overview of identity and authentication status.
+
+#### `/atproto whois <player or handle>`
+Looks up another player's AT Protocol identity.
+
+## Architecture
+
+```
+Player Command
+    ↓
+AtProtoCommands (Coroutine Scope)
+    ↓
+┌─────────────────────────────┐
+│   AtProtoSessionManager     │
+│  (Token Management)         │
+└─────────────────────────────┘
+    ↓
+┌─────────────────────────────┐
+│      AtProtoClient          │
+│  (HTTP + Slingshot)         │
+└─────────────────────────────┘
+    ↓
+┌─────────────────────────────┐
+│   Slingshot (Microcosm)     │
+│  PDS Resolution & Caching   │
+└─────────────────────────────┘
+    ↓
+AT Protocol Network
+    - Player's PDS (Authentication)
+    - plc.directory (DID Resolution)
+    ↓
+PlayerIdentityStore (Persistence)
+```
+
+## PDS Resolution with Slingshot
+
+The mod uses [Slingshot](https://slingshot.microcosm.blue) for identity resolution, which provides:
+
+1. **Fast Resolution**: Pre-cached PDS endpoints for quick lookups
+2. **resolveMiniDoc**: Returns `{did, handle, pds, pdsKnown}` in one call
+3. **Reliability**: Automatically falls back to standard resolution methods
+4. **Bi-directional Verification**: Only returns verified handle↔DID mappings
+
+**Example resolveMiniDoc response:**
+```json
+{
+  "did": "did:plc:abcdef123456",
+  "handle": "alice.bsky.social",
+  "pds": "https://morel.us-east.host.bsky.network",
+  "pdsKnown": true
+}
+```
+
+## Authentication Flow
+
+### 1. Initial Setup (Link)
+```
+Player runs: /atproto link alice.bsky.social
+    ↓
+Resolve via Slingshot → Get (DID, handle, PDS)
+    ↓
+Fetch profile to verify identity exists
+    ↓
+Store UUID ↔ (DID, handle) mapping
+```
+
+### 2. Authentication (Login)
+```
+Player runs: /atproto login alice.bsky.social abcd-1234-efgh-5678
+    ↓
+Resolve PDS URL via Slingshot
+    ↓
+POST /xrpc/com.atproto.server.createSession
+    Body: {identifier, password}
+    ↓
+Response: {did, handle, accessJwt, refreshJwt}
+    ↓
+Store session with tokens
+```
+
+### 3. Making Authenticated Requests
+```
+Mod needs to sync stats
+    ↓
+sessionManager.makeAuthenticatedRequest(uuid, "POST", "com.atproto.repo.createRecord", body)
+    ↓
+Check if access token needs refresh (>1.5 hours old)
+    ↓ (if needed)
+POST /xrpc/com.atproto.server.refreshSession
+    Header: Authorization: Bearer {refreshJwt}
+    ↓
+Update session with new tokens
+    ↓
+Make actual request with current accessJwt
+```
+
+## Data Storage
+
+### Identity Storage (`player-identities.json`)
+```json
+{
+  "version": 1,
+  "identities": [
+    {
+      "uuid": "550e8400-e29b-41d4-a716-446655440000",
+      "did": "did:plc:abcdef123456",
+      "handle": "alice.bsky.social",
+      "linkedAt": 1703001600000,
+      "lastVerified": 1703001600000
+    }
+  ]
+}
+```
+
+### Session Storage (`player-sessions.json`)
+```json
+{
+  "version": 1,
+  "sessions": [
+    {
+      "uuid": "550e8400-e29b-41d4-a716-446655440000",
+      "did": "did:plc:abcdef123456",
+      "handle": "alice.bsky.social",
+      "pdsUrl": "https://morel.us-east.host.bsky.network",
+      "accessJwt": "eyJ...",
+      "refreshJwt": "eyJ...",
+      "createdAt": 1703001600000,
+      "lastRefreshed": 1703001600000
+    }
+  ]
+}
+```
+
+## Security Considerations
+
+- **App Passwords Only**: Players should NEVER use their main account password
+- **Token Storage**: Tokens are stored on disk - server operators should secure the config directory
+- **Automatic Refresh**: Access tokens are refreshed automatically before expiration
+- **No Credential Storage**: App passwords are never stored, only the resulting JWT tokens
+- **Per-PDS**: Each player authenticates with their own PDS, maintaining decentralization
+
+## Error Handling
+
+All AT Protocol operations use Kotlin's `Result` type for error handling:
+- Network failures → Friendly error messages to players
+- Invalid identifiers → Format validation with helpful feedback
+- Authentication errors → Clear guidance about app passwords
+- Token expiration → Automatic refresh or re-login prompt
+
+Commands run in coroutine scope (`Dispatchers.IO`) to avoid blocking the server thread.
+
+## Creating App Passwords
+
+Players need to create an app password to authenticate:
+
+1. **Bluesky Users**:
+   - Go to Settings → Privacy and Security → App Passwords
+   - Click "Add App Password"
+   - Name it something descriptive (e.g., "Minecraft Server Name")
+   - Copy the password immediately
+
+2. **Other PDS Providers**:
+   - Check your PDS provider's documentation for app password creation
+   - The process is similar but may be in different locations
+
+3. **Security Tips**:
+   - Use a unique app password for each Minecraft server
+   - Never share your app password
+   - Revoke app passwords you're no longer using
+   - If compromised, revoke immediately and create a new one
+
+## Future Enhancements
+
+- OAuth device flow for better security (no passwords in chat)
+- Automatic session refresh on server restart
+- DPoP (Demonstrating Proof of Possession) support
+- Support for custom PDS instances with different auth flows
+- Integration with the lexicon records for automatic stat syncing
+- Web-based authentication portal

src/main/kotlin/com/jollywhoppers/atproto/examples/RecordCreationExample.kt

···
+package com.jollywhoppers.atproto.examples
+
+import com.jollywhoppers.atproto.AtProtoSessionManager
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.util.*
+
+/**
+ * Example showing how to create records in a player's AT Protocol repository.
+ * This demonstrates the foundation for syncing Minecraft data to AT Protocol.
+ */
+class RecordCreationExample(
+    private val sessionManager: AtProtoSessionManager
+) {
+    private val json = Json { prettyPrint = false }
+
+    /**
+     * Example: Create a player stats record
+     */
+    suspend fun createPlayerStatsRecord(
+        playerUuid: UUID,
+        statistics: List<Statistic>,
+        playtimeMinutes: Int,
+        level: Int
+    ): Result<String> = runCatching {
+        // Get the player's session (will auto-refresh if needed)
+        val session = sessionManager.getSession(playerUuid).getOrThrow()
+
+        // Build the record according to our lexicon
+        val record = PlayerStatsRecord(
+            `$type` = "com.jollywhoppers.minecraft.player.stats",
+            player = PlayerReference(
+                uuid = playerUuid.toString(),
+                username = "ExamplePlayer" // Would come from Minecraft player object
+            ),
+            server = ServerReference(
+                serverId = "example-server-id",
+                serverName = "Example Server"
+            ),
+            statistics = statistics,
+            playtimeMinutes = playtimeMinutes,
+            level = level,
+            gamemode = "survival",
+            syncedAt = java.time.Instant.now().toString()
+        )
+
+        // Create the record via XRPC
+        val requestBody = CreateRecordRequest(
+            repo = session.did,
+            collection = "com.jollywhoppers.minecraft.player.stats",
+            record = record
+        )
+
+        val response = sessionManager.makeAuthenticatedRequest(
+            uuid = playerUuid,
+            method = "POST",
+            endpoint = "com.atproto.repo.createRecord",
+            body = json.encodeToString(requestBody)
+        ).getOrThrow()
+
+        response
+    }
+
+    /**
+     * Example: Create a player profile record
+     */
+    suspend fun createPlayerProfileRecord(
+        playerUuid: UUID,
+        displayName: String?,
+        bio: String?,
+        publicStats: Boolean = true
+    ): Result<String> = runCatching {
+        val session = sessionManager.getSession(playerUuid).getOrThrow()
+
+        val record = PlayerProfileRecord(
+            `$type` = "com.jollywhoppers.minecraft.player.profile",
+            player = PlayerReference(
+                uuid = playerUuid.toString(),
+                username = "ExamplePlayer"
+            ),
+            displayName = displayName,
+            bio = bio,
+            createdAt = java.time.Instant.now().toString(),
+            publicStats = publicStats,
+            publicSessions = true
+        )
+
+        // For profile, we use rkey "self" since there's only one per account
+        val requestBody = CreateRecordRequestWithRkey(
+            repo = session.did,
+            collection = "com.jollywhoppers.minecraft.player.profile",
+            rkey = "self",
+            record = record
+        )
+
+        sessionManager.makeAuthenticatedRequest(
+            uuid = playerUuid,
+            method = "POST",
+            endpoint = "com.atproto.repo.putRecord",
+            body = json.encodeToString(requestBody)
+        ).getOrThrow()
+    }
+
+    /**
+     * Example: Create an achievement record
+     */
+    suspend fun createAchievementRecord(
+        playerUuid: UUID,
+        achievementId: String,
+        achievementName: String,
+        achievementDescription: String,
+        category: String,
+        isChallenge: Boolean = false
+    ): Result<String> = runCatching {
+        val session = sessionManager.getSession(playerUuid).getOrThrow()
+
+        val record = AchievementRecord(
+            `$type` = "com.jollywhoppers.minecraft.achievement",
+            player = PlayerReference(
+                uuid = playerUuid.toString(),
+                username = "ExamplePlayer"
+            ),
+            server = ServerReference(
+                serverId = "example-server-id",
+                serverName = "Example Server"
+            ),
+            achievementId = achievementId,
+            achievementName = achievementName,
+            achievementDescription = achievementDescription,
+            achievedAt = java.time.Instant.now().toString(),
+            category = category,
+            isChallenge = isChallenge
+        )
+
+        val requestBody = CreateRecordRequest(
+            repo = session.did,
+            collection = "com.jollywhoppers.minecraft.achievement",
+            record = record
+        )
+
+        sessionManager.makeAuthenticatedRequest(
+            uuid = playerUuid,
+            method = "POST",
+            endpoint = "com.atproto.repo.createRecord",
+            body = json.encodeToString(requestBody)
+        ).getOrThrow()
+    }
+
+    // Data classes matching our lexicon schemas
+
+    @Serializable
+    data class PlayerReference(
+        val uuid: String,
+        val username: String
+    )
+
+    @Serializable
+    data class ServerReference(
+        val serverId: String,
+        val serverName: String
+    )
+
+    @Serializable
+    data class Statistic(
+        val key: String,
+        val value: Int,
+        val category: String? = null
+    )
+
+    @Serializable
+    data class PlayerStatsRecord(
+        val `$type`: String,
+        val player: PlayerReference,
+        val server: ServerReference,
+        val statistics: List<Statistic>,
+        val playtimeMinutes: Int,
+        val level: Int,
+        val gamemode: String,
+        val dimension: String? = null,
+        val syncedAt: String
+    )
+
+    @Serializable
+    data class PlayerProfileRecord(
+        val `$type`: String,
+        val player: PlayerReference,
+        val displayName: String?,
+        val bio: String?,
+        val createdAt: String,
+        val updatedAt: String? = null,
+        val publicStats: Boolean,
+        val publicSessions: Boolean
+    )
+
+    @Serializable
+    data class AchievementRecord(
+        val `$type`: String,
+        val player: PlayerReference,
+        val server: ServerReference,
+        val achievementId: String,
+        val achievementName: String,
+        val achievementDescription: String,
+        val achievedAt: String,
+        val category: String,
+        val isChallenge: Boolean
+    )
+
+    @Serializable
+    data class CreateRecordRequest(
+        val repo: String,
+        val collection: String,
+        val record: Any
+    )
+
+    @Serializable
+    data class CreateRecordRequestWithRkey(
+        val repo: String,
+        val collection: String,
+        val rkey: String,
+        val record: Any
+    )
+}
+
+/**
+ * Usage example:
+ *
+ * ```kotlin
+ * val example = RecordCreationExample(sessionManager)
+ *
+ * // Create a stats snapshot
+ * val stats = listOf(
+ *     Statistic("minecraft:killed.minecraft.zombie", 42, "killed"),
+ *     Statistic("minecraft:mined.minecraft.diamond_ore", 15, "mined")
+ * )
+ *
+ * example.createPlayerStatsRecord(
+ *     playerUuid = player.uuid,
+ *     statistics = stats,
+ *     playtimeMinutes = 180,
+ *     level = 25
+ * ).onSuccess { response ->
+ *     logger.info("Stats synced successfully!")
+ * }.onFailure { error ->
+ *     logger.error("Failed to sync stats", error)
+ * }
+ * ```
+ */

src/main/resources/lexicons/README.md

···
+# atproto-connect Lexicons
+
+This directory contains Lexicon schema definitions for the `com.jollywhoppers.minecraft.*` namespace, enabling Minecraft data to be stored and shared on the AT Protocol network.
+
+## Schema Overview
+
+### Core Definitions
+
+**`com.jollywhoppers.minecraft.defs`**
+- Common type definitions used across all Minecraft lexicons
+- Includes `playerReference`, `serverReference`, and `statistic` types
+
+### Player Data
+
+**`com.jollywhoppers.minecraft.player.profile`** (key: `literal:self`)
+- Links a Minecraft player UUID to their AT Protocol identity
+- Single record per account serving as the primary identity record
+- Includes privacy controls for stats and session visibility
+
+**`com.jollywhoppers.minecraft.player.stats`** (key: `tid`)
+- Snapshots of player statistics (blocks mined, mobs killed, etc.)
+- Suitable for cross-server leaderboards
+- Can be synced periodically or on significant milestones
+
+**`com.jollywhoppers.minecraft.player.session`** (key: `tid`)
+- Individual play session records (join/leave times)
+- Tracks playtime and connection history
+- Useful for activity tracking and analytics
+
+### Achievements
+
+**`com.jollywhoppers.minecraft.achievement`** (key: `tid`)
+- Records when players earn achievements/advancements
+- Supports both vanilla and custom achievements
+- Can be scoped to specific servers or global
+
+### Leaderboards
+
+**`com.jollywhoppers.minecraft.leaderboard`** (key: `tid`)
+- Pre-computed leaderboard entries for specific statistics
+- Supports server-specific and global leaderboards
+- Can track different time periods (all-time, monthly, weekly, daily)
+
+### Server Status
+
+**`com.jollywhoppers.minecraft.server.status`** (key: `literal:self`)
+- Server information and current status
+- Player counts, version info, server settings
+- Useful for server discovery and monitoring
+
+## Record Keys
+
+- **`tid`**: Time-ordered identifier - used for records that occur multiple times
+- **`literal:self`**: Single instance record - only one per account
+
+## Usage Example
+
+When a player completes a milestone, the mod would:
+
+1. Read current stats from the Minecraft player data
+2. Create a `com.jollywhoppers.minecraft.player.stats` record
+3. Optionally update the `com.jollywhoppers.minecraft.leaderboard` if they rank
+4. Publish to the player's AT Protocol repository
+
+## Data Flow
+
+```
+Minecraft Server (Fabric)
+    ↓
+Player Events (blocks mined, mobs killed, etc.)
+    ↓
+atproto-connect Mod
+    ↓
+Create/Update Lexicon Records
+    ↓
+AT Protocol PDS
+    ↓
+Federated Network (visible to all indexers)
+    ↓
+Custom AppViews (leaderboards, stats displays)
+```
+
+## Privacy Considerations
+
+- Players control what data is synced via `publicStats` and `publicSessions` flags
+- Server operators can configure which statistics are tracked
+- All data is published to the player's own AT Protocol repository
+- Players can delete their data at any time
+
+## Future Enhancements
+
+- Event records (player kills, deaths, notable achievements)
+- Trading/economy tracking
+- Guild/team statistics
+- Custom server-specific lexicons
+- Rich media attachments (screenshots of achievements)
+
+## References
+
+- [AT Protocol Lexicon Specification](https://atproto.com/specs/lexicon)
+- [AT Protocol Data Model](https://atproto.com/specs/data-model)
+- [Lexicon Style Guide](https://atproto.com/guides/lexicon-style-guide)

src/main/resources/lexicons/com.jollywhoppers.minecraft.achievement.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.achievement",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Achievement or advancement earned by a player in Minecraft.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["player", "achievementId", "achievedAt"],
+        "properties": {
+          "player": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#playerReference",
+            "description": "Player who earned the achievement"
+          },
+          "server": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#serverReference",
+            "description": "Server where the achievement was earned"
+          },
+          "achievementId": {
+            "type": "string",
+            "description": "Achievement identifier (e.g., 'minecraft:story/mine_diamond')",
+            "maxLength": 256
+          },
+          "achievementName": {
+            "type": "string",
+            "description": "Human-readable achievement name",
+            "maxLength": 256
+          },
+          "achievementDescription": {
+            "type": "string",
+            "description": "Achievement description",
+            "maxLength": 1000
+          },
+          "achievedAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When the achievement was earned"
+          },
+          "category": {
+            "type": "string",
+            "description": "Achievement category (e.g., 'story', 'nether', 'end', 'adventure', 'husbandry')",
+            "maxLength": 64
+          },
+          "isChallenge": {
+            "type": "boolean",
+            "description": "Whether this is a challenge advancement",
+            "default": false
+          }
+        }
+      }
+    }
+  }
+}

src/main/resources/lexicons/com.jollywhoppers.minecraft.defs.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.defs",
+  "defs": {
+    "playerReference": {
+      "type": "object",
+      "description": "Reference to a Minecraft player",
+      "required": ["uuid", "username"],
+      "properties": {
+        "uuid": {
+          "type": "string",
+          "description": "Player's Minecraft UUID",
+          "maxLength": 36
+        },
+        "username": {
+          "type": "string",
+          "description": "Player's Minecraft username",
+          "maxLength": 16
+        }
+      }
+    },
+    "serverReference": {
+      "type": "object",
+      "description": "Reference to a Minecraft server",
+      "required": ["serverId", "serverName"],
+      "properties": {
+        "serverId": {
+          "type": "string",
+          "description": "Unique server identifier",
+          "maxLength": 128
+        },
+        "serverName": {
+          "type": "string",
+          "description": "Human-readable server name",
+          "maxLength": 256
+        },
+        "serverAddress": {
+          "type": "string",
+          "description": "Server address (optional)",
+          "maxLength": 512
+        }
+      }
+    },
+    "statistic": {
+      "type": "object",
+      "description": "A single statistic entry",
+      "required": ["key", "value"],
+      "properties": {
+        "key": {
+          "type": "string",
+          "description": "Statistic identifier (e.g., 'minecraft:mined', 'minecraft:killed')",
+          "maxLength": 256
+        },
+        "value": {
+          "type": "integer",
+          "description": "Statistic value"
+        },
+        "category": {
+          "type": "string",
+          "description": "Category of statistic (e.g., 'mined', 'killed', 'used', 'broken')",
+          "maxLength": 64
+        }
+      }
+    }
+  }
+}

src/main/resources/lexicons/com.jollywhoppers.minecraft.leaderboard.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.leaderboard",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Leaderboard entry for a specific statistic. Useful for displaying top players across servers.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["player", "statisticKey", "value", "updatedAt"],
+        "properties": {
+          "player": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#playerReference",
+            "description": "Player on the leaderboard"
+          },
+          "server": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#serverReference",
+            "description": "Server scope (omit for global leaderboard)"
+          },
+          "statisticKey": {
+            "type": "string",
+            "description": "The statistic being ranked (e.g., 'total_kills', 'diamonds_mined', 'playtime')",
+            "maxLength": 256
+          },
+          "value": {
+            "type": "integer",
+            "description": "The statistic value"
+          },
+          "rank": {
+            "type": "integer",
+            "description": "Player's rank for this statistic",
+            "minimum": 1
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When this leaderboard entry was last updated"
+          },
+          "period": {
+            "type": "string",
+            "description": "Time period for leaderboard (e.g., 'all-time', 'monthly', 'weekly', 'daily')",
+            "enum": ["all-time", "yearly", "monthly", "weekly", "daily"],
+            "default": "all-time"
+          }
+        }
+      }
+    }
+  }
+}

src/main/resources/lexicons/com.jollywhoppers.minecraft.player.profile.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.player.profile",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Links a Minecraft player identity to an AT Protocol account. This is the primary identity record.",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "required": ["player", "createdAt"],
+        "properties": {
+          "player": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#playerReference",
+            "description": "Minecraft player identity"
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Display name for the player",
+            "maxLength": 128,
+            "maxGraphemes": 64
+          },
+          "bio": {
+            "type": "string",
+            "description": "Player bio or description",
+            "maxLength": 2560,
+            "maxGraphemes": 256
+          },
+          "primaryServer": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#serverReference",
+            "description": "Player's primary/home server"
+          },
+          "favoriteGameMode": {
+            "type": "string",
+            "description": "Preferred game mode",
+            "enum": ["survival", "creative", "adventure", "spectator"]
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When this profile was created"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When this profile was last updated"
+          },
+          "publicStats": {
+            "type": "boolean",
+            "description": "Whether stats should be publicly visible",
+            "default": true
+          },
+          "publicSessions": {
+            "type": "boolean",
+            "description": "Whether play sessions should be publicly visible",
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}

src/main/resources/lexicons/com.jollywhoppers.minecraft.player.session.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.player.session",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "A single Minecraft play session. Tracks when a player joined and left a server.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["player", "joinedAt"],
+        "properties": {
+          "player": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#playerReference",
+            "description": "Player who had this session"
+          },
+          "server": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#serverReference",
+            "description": "Server where the session occurred"
+          },
+          "joinedAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When the player joined the server"
+          },
+          "leftAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When the player left the server (null if still online)"
+          },
+          "durationMinutes": {
+            "type": "integer",
+            "description": "Session duration in minutes",
+            "minimum": 0
+          },
+          "quitReason": {
+            "type": "string",
+            "description": "Reason for disconnection",
+            "maxLength": 256
+          }
+        }
+      }
+    }
+  }
+}

src/main/resources/lexicons/com.jollywhoppers.minecraft.player.stats.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.player.stats",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Player statistics snapshot from Minecraft. Suitable for leaderboards and cross-server tracking.",
+      "key": "tid",
+      "record": {
+        "type": "object",
+        "required": ["player", "statistics", "syncedAt"],
+        "properties": {
+          "player": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#playerReference",
+            "description": "Player this stat snapshot belongs to"
+          },
+          "server": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#serverReference",
+            "description": "Server where these stats were recorded"
+          },
+          "statistics": {
+            "type": "array",
+            "description": "Array of player statistics",
+            "items": {
+              "type": "ref",
+              "ref": "com.jollywhoppers.minecraft.defs#statistic"
+            },
+            "maxLength": 1000
+          },
+          "playtimeMinutes": {
+            "type": "integer",
+            "description": "Total playtime in minutes",
+            "minimum": 0
+          },
+          "level": {
+            "type": "integer",
+            "description": "Player experience level",
+            "minimum": 0
+          },
+          "gamemode": {
+            "type": "string",
+            "description": "Current gamemode",
+            "enum": ["survival", "creative", "adventure", "spectator"],
+            "default": "survival"
+          },
+          "dimension": {
+            "type": "string",
+            "description": "Current dimension",
+            "maxLength": 256
+          },
+          "syncedAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When these stats were synced to AT Protocol"
+          }
+        }
+      }
+    }
+  }
+}

src/main/resources/lexicons/com.jollywhoppers.minecraft.server.status.json

···
+{
+  "lexicon": 1,
+  "id": "com.jollywhoppers.minecraft.server.status",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Minecraft server status snapshot. Can be used for server discovery and monitoring.",
+      "key": "literal:self",
+      "record": {
+        "type": "object",
+        "required": ["server", "version", "updatedAt"],
+        "properties": {
+          "server": {
+            "type": "ref",
+            "ref": "com.jollywhoppers.minecraft.defs#serverReference",
+            "description": "Server information"
+          },
+          "version": {
+            "type": "string",
+            "description": "Minecraft server version",
+            "maxLength": 64
+          },
+          "protocolVersion": {
+            "type": "integer",
+            "description": "Minecraft protocol version number"
+          },
+          "maxPlayers": {
+            "type": "integer",
+            "description": "Maximum player capacity",
+            "minimum": 0
+          },
+          "onlinePlayers": {
+            "type": "integer",
+            "description": "Current number of online players",
+            "minimum": 0
+          },
+          "playerSample": {
+            "type": "array",
+            "description": "Sample of online players",
+            "items": {
+              "type": "ref",
+              "ref": "com.jollywhoppers.minecraft.defs#playerReference"
+            },
+            "maxLength": 100
+          },
+          "motd": {
+            "type": "string",
+            "description": "Server message of the day",
+            "maxLength": 500,
+            "maxGraphemes": 100
+          },
+          "gameMode": {
+            "type": "string",
+            "description": "Primary game mode",
+            "maxLength": 64
+          },
+          "difficulty": {
+            "type": "string",
+            "description": "Server difficulty",
+            "enum": ["peaceful", "easy", "normal", "hard"],
+            "default": "normal"
+          },
+          "hardcore": {
+            "type": "boolean",
+            "description": "Whether hardcore mode is enabled",
+            "default": false
+          },
+          "pvpEnabled": {
+            "type": "boolean",
+            "description": "Whether PvP is enabled",
+            "default": true
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "When this status was recorded"
+          }
+        }
+      }
+    }
+  }
+}