Document shared character sessions in Gathering and GunsAndGadgets

projects/Gathering/README.md

@@ -10,11 +10,14 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 Gathering builds with Java **21** against
 `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
-`2.0.1` and RPCharacters `2.0.2` release artifacts with the shared dependency
+`2.3.0` and RPCharacters `2.16.0` release artifacts with the shared dependency
 installer. The build also prepares checksum-verified MMOCore `1.13.1-SNAPSHOT` and
 MythicLib `1.7.1-SNAPSHOT` inputs from the private ServerAssets repository.
 
-At runtime, `plugin.yml` requires TLibs and RPCharacters. MMOCore is optional;
+At runtime, `plugin.yml` requires TLibs and RPCharacters. Character identity comes
+from the [shared TLibs session API](../TLibs/character-identity.md). The direct
+RPCharacters dependency remains for creation-layer wisdom and intelligence;
+MMOCore totals would change discovery odds. MMOCore is optional;
 the profession bonus to discovery chance is only applied when that plugin is
 enabled. MythicLib is a compile input only and is not declared in `plugin.yml`.
 

projects/Gathering/overview.md

@@ -43,7 +43,15 @@ spot type identifier.
 
 ## Discovery and gathering
 
-Only players with an active RPCharacters character take part. When
+Normal discovery, visibility and harvesting require a ready session from the
+[shared character API](../TLibs/character-identity.md). They wait while the provider
+is unavailable or character setup is pending; an account UUID never substitutes
+for a character UUID. Existing discoveries retain their stored character UUIDs,
+so reconnecting or switching back preserves them. Passive discovery also checks
+that the RPCharacters model supplying attributes matches that session.
+
+Wisdom and intelligence use the character sheet's creation-layer attributes,
+without extra MMOCore allocations or equipment bonuses. When
 `passive-discovery.enabled` is true, every `interval-seconds` the plugin rolls
 once for each undiscovered spot within `radius` blocks of each such player. The
 chance is `base-chance` plus wisdom × `wisdom-weight`, intelligence ×

projects/GunsAndGadgets/operations.md

@@ -36,3 +36,35 @@ reloads use the first compatible ammunition carried.
 The action bar confirms the selection and carried amount, or reports that no
 compatible ammunition is available. Selection is blocked while the gun is
 reloading.
+
+
+## Character sessions and reload cleanup
+
+The build pins TLibs 2.3.0. GunsAndGadgets listens directly for shared
+`CharacterSessionEndEvent` events and no longer has a compile dependency or
+`softdepend` on RPCharacters. RPCharacters 2.16.0 supplies these events when
+installed; ordinary gun use remains available without a character provider. With
+a provider present, gun use waits until the character has a ready session.
+
+A reload reserves the exact ammunition stacks it consumes and captures the current
+session. Its timer checks that session before progressing; a stale session or a
+provider appearing during account fallback cancels it. Switching character,
+permanent death, quit and provider shutdown cancel the reload while the outgoing
+inventory is still loaded, before it is saved or replaced. Cancellation restores
+the reserved items, drops only overflow and clears the reload marker. Duplicate
+end/quit notifications and late reload timers cannot refund twice or cancel a
+newer reload. GunsAndGadgets also refunds active reloads on its own disable,
+covering either plugin shutdown order. Its quit listener remains available when
+there is no identity provider.
+
+The deferred held-slot validation captures the current session. It stops if that
+session ends, even when the player switches away and back to the same character.
+It also stops on disconnect, pending character readiness, or a provider appearing
+between scheduling and completion.
+
+For runtime validation, start a reload and exercise each session-end reason.
+Confirm ammunition returns to the outgoing inventory before its save, the next
+character receives no old reload completion, and clean shutdown preserves exact
+item metadata and quantities. Repeat without RPCharacters to check quit cleanup.
+See the [shared identity API](../TLibs/character-identity.md) and
+[RPCharacters provider](../RPCharacters/docs/character-identity.md).