Document BirdMessenger character sessions and mail ownership

projects/BirdMessenger/README.md

@@ -10,7 +10,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 Run Maven with **JDK 21** from the source checkout. The POM sets `maven.compiler.release=21` and resolves `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT` with `provided` scope from the PaperMC Maven repository. The plugin descriptor declares `api-version: 1.21.10`.
 
-Install these matching Java 21 TFMC artifacts into local Maven before building: `me.plugins:tlibs:2.0.0`, `net.tfminecraft:rpcharacters:2.0.1`. Use the [shared installer](../TLibs/README.md) for published dependencies, or `mvn clean install` from matching source versions. CI uses the shared dependency setup actions.
+Install these matching Java 21 TFMC artifacts into local Maven before building: `me.plugins:tlibs:2.3.0`, `net.tfminecraft:rpcharacters:2.16.0`. Use the [shared installer](../TLibs/README.md) for published dependencies, or `mvn clean install` from matching source versions. CI uses the shared dependency setup actions.
 
 Populate `libs/` with the exact files and hashes listed in `.github/dependencies.sha256`. `.github/scripts/prepare-release.sh` downloads those pinned private assets when supplied with the approved dependency token.
 
@@ -34,7 +34,7 @@ Use `mvn clean install` when another plugin needs the result as a Maven dependen
 
 ## Runtime and configuration
 
-The manifest requires TLibs and marks RPCharacters, TFMCWeb and ItemsAdder optional. The character picker needs RPCharacters; furniture mailboxes need ItemsAdder; offline Discord notifications need TFMCWeb and `discord.enabled`. `/birdmessenger reload` requires `birdmessenger.reload` (op by default). See the mailbox guide below for interaction checks.
+The manifest requires TLibs and marks RPCharacters, TFMCWeb and ItemsAdder optional. Sending requires a ready character session from TLibs, and the character picker needs RPCharacters; furniture mailboxes need ItemsAdder; offline Discord notifications need TFMCWeb and `discord.enabled`. `/birdmessenger reload` requires `birdmessenger.reload` (op by default). See the mailbox guide below for interaction checks.
 
 ## Guides
 

projects/BirdMessenger/overview.md

@@ -23,6 +23,37 @@ character from the recipient list, or `/rpcharacter mail on` to restore it. If a
 recipient opts out before a sender confirms, the letter is returned; already-sent
 mail still arrives.
 
+## Character sessions
+
+Mailbox sending requires a ready character. The letter slot, recipient picker,
+queued picker opening and skin refresh belong to the same player connection and
+character activation. Switching away and back does not revive an old menu.
+Ending that session closes its menus and returns unsent letters to the outgoing
+inventory before RPCharacters saves it. Plugin shutdown also returns letters from
+current sessions. When that inventory is no longer safe to use, the letter is
+queued for its captured owner and character instead. Storage errors are logged;
+failed unsent refunds remain in memory for retry on character start and plugin
+shutdown. Repair a reported storage problem before stopping the plugin.
+
+Letter editing, signing and opening preserve the original item checks and also
+verify the captured session before changing an item on the next tick. While a
+character provider is registered but no character is ready, edits and signatures
+are refused; sealed books remain readable without rewriting the item. Standalone
+letter editing remains available without a provider, provided one has not arrived
+before the delayed write.
+
+In-flight mail belongs to the recipient character and survives session changes.
+Delivery requires a ready session for the stored owner and character. Pending
+mail is removed one letter at a time, checking the same session between letters;
+a switch during delivery leaves the rest queued. Existing UUID text is preserved,
+including uppercase spelling. Malformed character IDs and mail for another owner
+are retained and are not delivered to the current character.
+
+The shared TLibs API supplies session identity. RPCharacters still supplies the
+mail-specific opted-in recipient list, head textures and flight destinations.
+BirdMessenger requires TLibs 2.3.0 or newer; missing provider registration blocks
+sending and delivery until it becomes available.
+
 ## Mail recovery
 
 Mail is stored in `plugins/BirdMessenger/in_flight_mail.yml` and
@@ -45,3 +76,11 @@ Before deployment, verify on a test server with ItemsAdder:
 - Sneak-break: the mailbox can be removed, subject to existing region protection.
 - Right-click and send sealed and opened letters: pages and delivery stay intact.
 - Unrelated items and ordinary books are rejected; other furniture breaks normally.
+- Switch characters from both the letter slot and recipient picker: the outgoing
+  character keeps the unsent letter and the next character receives no stale menu.
+- Switch away and back while a picker refresh or letter edit is queued: old work
+  cannot change the current inventory.
+- Receive several pending letters, switching during delivery: remaining letters
+  wait for a ready session of their stored owner and character.
+- Restart with pending and in-flight mail: delivery resumes without changing
+  recipient opt-out behavior or stored character IDs.