Describe finding living characters by real name

projects/RPCharacters/docs/character-identity.md

@@ -3,7 +3,7 @@
 [RPCharacters](../README.md) · [TLibs API](../../TLibs/character-identity.md)
 
 RPCharacters provides TLibs' `CharacterIdentity` service through Bukkit's
-`ServicesManager`. The build pins TLibs 2.4.1; install that release or a compatible
+`ServicesManager`. The build pins TLibs 2.5.0; install that release or a compatible
 newer one before RPCharacters. Consumers use the `Characters` facade rather than
 reading RPCharacters files or waiting a fixed number of ticks after login.
 
@@ -36,7 +36,12 @@ Login also compares loaded character IDs against the directory. An account whose
 records cannot be loaded completely is disconnected before admission or saves.
 
 `CharacterInfo.name` is the real, plain character name. `displayName(player)` uses
-the current mask and temporary alias rules. The playtime field is the existing
+the current mask and temporary alias rules.
+
+`findByName(name)` first overlays every loaded account, then scans the in-memory
+directory, so it reads no files. It returns every `ALIVE` character whose real name
+equals the trimmed `name`, ignoring case. Dead and missing characters, aliases,
+masks and temporary aliases never match, and unavailable accounts are skipped. The playtime field is the existing
 `online-playtime-seconds` counter, with no visibility filtering.
 
 ## Sessions and readiness
@@ -125,7 +130,7 @@ covering the whole account.
 
 Run `mvn clean verify` with Java 21 and pinned dependencies installed. The unit
 suite checks directory corruption and duplicates, skipped stray entries, the
-legacy `lastPlayed` fallback, immutable snapshots, live updates, delayed
+legacy `lastPlayed` fallback, name lookups, immutable snapshots, live updates, delayed
 readiness, reconnects, repeated-character switches, event order, quit and
 shutdown cleanup, cancelled and inactive deaths, distinct death IDs after
 revival, failed saves, and activation failures after a committed death or

projects/TLibs/character-identity.md

@@ -44,10 +44,14 @@ caller.
 | `deathId(UUID characterId)` | Most recent saved death ID, including after revival; empty when unknown. |
 | `characters(UUID ownerId)` | Every character on the account, as an immutable copy. Empty means the records could not be read; an empty list means the account has none. |
 | `lastPlayed(UUID ownerId)` | The character the account played most recently, dead or alive. |
+| `findByName(String name)` | Living characters whose real name equals `name`, ignoring case, as an immutable list. Masks and aliases never match. Several characters can share a name, so callers that need one character must handle more than one match. |
 | `displayName(Player)` | The name other players see now, including masks and aliases. |
 
-Without a provider, lookups return empty, `isCurrent` returns false and
-`displayName` returns the account name. That fallback is acceptable for display and
+`findByName` was added in TLibs 2.5.0. The interface has an empty default, so a
+provider built against an older TLibs finds nobody.
+
+Without a provider, lookups return empty, `findByName` returns an empty list,
+`isCurrent` returns false and `displayName` returns the account name. That fallback is acceptable for display and
 gameplay checks. Ownership and money must wait for `available()`, and must never
 treat an empty `characters` result as an account with no characters.