docs: describe feature ownership and manual dev/main updates

projects/BirdMessenger/README.md

@@ -27,3 +27,7 @@ The manifest requires TLibs and marks RPCharacters, TFMCWeb and ItemsAdder optio
 ## Builds and releases
 
 See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.
+
+## Shared feature ownership
+
+See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.

projects/BirdMessenger/overview.md

@@ -5,8 +5,8 @@ Right-click the mailbox to send letters. Ordinary left-clicks are protected;
 sneak-break to remove the mailbox deliberately.
 
 The default `letter: ia.iasurvival:letter` accepts blank, sealed and opened
-letter variants, including for existing configurations. Custom legacy values
-still match only that item. An optional `letters` list overrides `letter`:
+letter variants, including for existing configurations. The default also accepts letter variants configured by the transferred sealing
+feature. Custom legacy values still match only that item. An optional `letters` list overrides `letter`:
 
 ```yaml
 letters:

projects/Cooking/README.md

@@ -16,7 +16,7 @@ Use JDK 21, install the matching TLibs Maven artifact (`me.plugins:tlibs`, versi
 
 ## Runtime and configuration
 
-The plugin registers food item paths with TLibs and integrates furniture stations, TFMCCore, crops and husbandry. The manifest requires TLibs, InteractibleFurniture and TFMCCore; RPCharacters, MMOCore, CustomCrops, SimpleFactions and CustomFishing enable additional integrations. `/cooking` requires `cooking.admin` (op by default). The guides below define crop and husbandry behavior and their configuration boundaries.
+The plugin registers food item paths with TLibs and integrates furniture stations, TLibs inventory scanning, crops and husbandry. The manifest requires TLibs 2.1.0 or newer and InteractibleFurniture; RPCharacters, MMOCore, CustomCrops, SimpleFactions and CustomFishing enable additional integrations. `/cooking` requires `cooking.admin` (op by default). The guides below define crop and husbandry behavior and their configuration boundaries.
 
 ## Guides
 
@@ -26,3 +26,7 @@ The plugin registers food item paths with TLibs and integrates furniture station
 ## Builds and releases
 
 See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.
+
+## Shared feature ownership
+
+See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.

projects/Magic/README.md

@@ -13,3 +13,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 ## Builds and releases
 
 See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.
+
+## Shared feature ownership
+
+See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.

projects/Magic/docs/SYSTEM.md

@@ -88,7 +88,7 @@ Sit with GSit on the circle center (must be in a vehicle). Eight InteractibleFur
 
 No chat or action bar. A white starter orb appears in front of you; left-click hitscan (VehicleFramework-style) begins the orbit field. White orbs are Flow, red are Surge. Mix follows Equilibrium (`whiteChance = 0.5 * (1 + eq/max)`). Hitting red starts a 10s all-Surge lock; another red hit refreshes it.
 
-Each hit costs 1 Focus (TFMCCore, character-keyed). Flow nudges Equilibrium up; Surge nudges it down. Resonance toward cap `sum(element power on sockets) / 8`. Charged artifacts supply usable aura, adjusted by their care state. Empty artifacts do not start a session; missing furniture means no session.
+Each hit costs 1 Focus (RPCharacters, character-keyed). Flow nudges Equilibrium up; Surge nudges it down. Resonance toward cap `sum(element power on sockets) / 8`. Charged artifacts supply usable aura, adjusted by their care state. Empty artifacts do not start a session; missing furniture means no session.
 
 ## Persistence (MagicProfile)
 
@@ -104,11 +104,10 @@ Admin `/magic open` without a character stays ephemeral (nothing saved). Drift s
 
 ## Dependencies
 
-- **TLibs** (required) - item refs, formatHex
+- **TLibs** (required, 2.1.0 or newer) - item refs, formatHex, inventory scanning
 - **ItemsAdder** (required) - `ia.` icons in gui.yml / elements
-- **TFMCCore** (required) - character Focus pool
+- **RPCharacters** (required, 2.1.0 or newer) - character Focus pool, character head and per-character MagicProfile persistence
 - **InteractibleFurniture** (required) - pedestals
-- **RPCharacters** (soft) - character head and per-character MagicProfile persistence
 
 ## Commands
 

projects/RPCharacters/README.md

@@ -20,3 +20,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 ## Builds and releases
 
 See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.
+
+## Shared feature ownership
+
+See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.

projects/Research/README.md

@@ -10,12 +10,12 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 Research builds with Java **21** against
 `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT`. Install the pinned TLibs
-`2.0.1` and TFMCCore `2.0.1` release artifacts with the shared dependency
+`2.0.1` and RPCharacters `2.1.0` release artifacts with the shared dependency
 installer. The build also prepares checksum-verified MMOCore `1.13.1` and
 MythicLib `1.7` inputs from the private ServerAssets repository.
 
 At runtime, `plugin.yml` requires MMOItems, MythicLib, ItemsAdder, TLibs, and
-TFMCCore. The code reaches MMOItems and ItemsAdder only through TLibs item
+RPCharacters. The code reaches MMOItems and ItemsAdder only through TLibs item
 paths. MMOCore is declared as a soft dependency, but the discovery attribute
 lookup calls MMOCore classes directly, so install MMOCore wherever Research
 runs.
@@ -28,3 +28,7 @@ runs.
 
 See the [shared pipeline guide](../../PIPELINES.md) for development artifacts,
 release tags, private dependency access, and release verification.
+
+## Shared feature ownership
+
+See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.

projects/Research/overview.md

@@ -113,9 +113,9 @@ open station menus before changing `labels` titles or `colors.inventory_title`.
 
 ## Integrations
 
-- **TFMCCore Focus.** Mental points are the TFMCCore Focus pool for the player's
+- **RPCharacters Focus.** Mental points are the RPCharacters Focus pool for the player's
   active RPCharacters character, shared with Magic meditation. The cap and
-  regeneration, including attribute bonuses, are set in TFMCCore `focus.yml`. A
+  regeneration, including attribute bonuses, are set in RPCharacters `focus.yml`. A
   player without an active character has no points and cannot experiment.
 - **MMOCore.** The discovery attribute is read as the attribute's total value;
   a missing attribute counts as zero.

projects/TFMCCore/README.md

@@ -6,7 +6,8 @@ Technical documentation is maintained here. Run commands from the source checkou
 
 TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
 
-- [README.md](overview.md)
+- [Overview](overview.md)
+- [Feature ownership and manual updates](ownership.md)
 - [src/main/java/net/tfminecraft/tfmccore/stats/ARCHITECTURE.md](src/main/java/net/tfminecraft/tfmccore/stats/ARCHITECTURE.md)
 - [src/main/java/net/tfminecraft/tfmccore/stats/STATS.md](src/main/java/net/tfminecraft/tfmccore/stats/STATS.md)
 

projects/TFMCCore/ownership.md

@@ -0,0 +1,108 @@
+# Shared feature ownership
+
+| Feature | Owner | API / administration |
+| --- | --- | --- |
+| Inventory scanning | TLibs | `net.tfminecraft.tlibs.itemscan.ItemScanService` and `ItemScanHandler` |
+| Character focus | RPCharacters | `RPCharacters.getFocusService()`; `/focus restore <player>` and `/focus reload` |
+| Letter editing, sealing and opening | BirdMessenger | `letters-config.yml`; `/birdmessenger reload` |
+
+Cooking and Magic subscribe directly to TLibs scanning. Magic and Research read
+and spend focus through RPCharacters. These consumers do not depend on TFMCCore.
+Core owns server rules, custom drops, MMOItems station interactions, statistics,
+whistles and item name/lore stones.
+
+## Inventory scanning
+
+TLibs starts and stops the scanner with its own lifecycle. Consumers with a hard
+TLibs dependency subscribe during enable and unsubscribe during disable. Only
+TLibs calls `start` or `stop`.
+
+The scanner processes one online player every two ticks, scans inventory opens
+immediately, and calls pickup handlers with a null inventory and slot -1. Handlers
+run synchronously in registration order and own item mutation. The scanner uses
+Paper's global Bukkit scheduler and does not support Folia.
+
+## Character focus
+
+RPCharacters owns `focus.yml` and `data/focus/<character-id>.json`. Character
+activation switches balances, quitting saves them, and one timer applies configured
+regeneration. Point limits, attribute bonuses and offline regeneration are
+configured in `focus.yml`. Corrupt or unreadable records are reported and leave
+the affected character's focus unavailable; they are not replaced with fresh points.
+
+`RPCharacters.getFocusService()` exposes balance, maximum, spending, granting and
+restoration. It returns null if focus has not started successfully. Administrators
+need `rpchar.focus.admin` (operator by default) for `/focus restore <player>` and
+`/focus reload`. RPCharacters' general reload also reloads focus configuration.
+
+## Letters
+
+BirdMessenger owns `letters-config.yml` and book edit/sign/open listeners, in
+addition to delivery. The `tfmccore:sealed_letter` persistent item key remains the
+stable identifier for sealed items; there is no alternative-key fallback.
+
+The default mail acceptance includes the configured blank/sealed/opened letter
+variants. An explicit `letters` list or a custom `letter` setting remains
+authoritative. Check that these settings accept the items used by the server.
+
+## Build order
+
+1. Build and publish TLibs 2.1.0 and RPCharacters 2.1.0 from their merged source.
+   Verify the release JARs, embedded versions, checksums and build metadata.
+2. Build Cooking, Magic and Research against those published provider versions.
+   Require their pinned-dependency CI builds to pass. Build BirdMessenger and
+   TFMCCore from the merged source as well.
+3. Stage all seven JARs together: TLibs, RPCharacters, Cooking, Magic, Research,
+   BirdMessenger and TFMCCore. Record the source commit and checksum of each JAR;
+   use the same verified set for dev and main. Publishing a release does not
+   update either server.
+
+## Manual dev and main update
+
+The installations are controlled together. There are no automatic data imports,
+version-detection paths, old API wrappers or old command aliases. Update the full
+plugin set while each server is stopped. Complete and verify dev before main.
+
+Back up the plugin jars and all affected configuration/data folders. Before first
+starting the updated plugins, manually copy these files under that server's
+`plugins` directory:
+
+| Copy from | Copy to |
+| --- | --- |
+| `TFMCCore/focus.yml` | `RPCharacters/focus.yml` |
+| `TFMCCore/data/focus/*.json` | `RPCharacters/data/focus/` (same filenames) |
+| `TFMCCore/letters-config.yml` | `BirdMessenger/letters-config.yml` |
+
+Create destination directories as needed. Compare existing destination files
+before copying and resolve differences explicitly; do not overwrite newer
+balances or server settings. Keep the source copies in the backup until the
+update is verified. Starting without the copies creates defaults/new focus state,
+so perform the file transfer first. No scanner data needs moving.
+
+Install the updated TLibs, RPCharacters, BirdMessenger, Core, Cooking, Magic and
+Research jars as one coordinated set. Update staff permissions and configured
+commands to use `/focus` and `/birdmessenger reload`. Core's reload targets now
+cover its own configuration, drops, stations, stats, whistle and lorestones.
+Remove the replaced JARs from the plugins directory so each plugin has exactly
+one installed JAR. Use a full stop/start rather than a plugin reload.
+
+Consumer builds require TLibs 2.1.0 for scanning and RPCharacters 2.1.0 for focus;
+BirdMessenger's letter feature targets 1.1.0. Publish provider releases before
+building dependent consumers through the pinned-release CI. Local source-built
+candidates can verify the changes together, but are not published releases.
+
+After startup, verify food freshness/fish conversion, artifact updates, focus
+spending and character switching, offline regeneration, restart persistence,
+letter editing/sealing/opening in both hands, and queued mail. Compare copied balances and item
+content before exercising them. Repeat the same procedure on main after dev
+passes. Unit tests do not replace these Paper integration checks.
+
+Copy main's own current files during main's maintenance window; do not copy dev's
+focus balances over main. Sealed items keep their existing identifier and need
+no item conversion. No scanner files need transferring.
+
+For rollback, stop the server and restore a compatible set of jars/configuration.
+If players have used the updated system, manually reconcile the current
+RPCharacters focus records back into Core before restoring its ownership; the
+pre-update backup no longer contains the latest balances. Retain current mail
+storage and reconcile any changed letter settings as well.

projects/TLibs/README.md

@@ -2,7 +2,7 @@
 
 [Source repository](https://github.com/TF-Minecraft/TLibs) · [All projects](../../README.md)
 
-TLibs provides shared item and block APIs, MMOItems rebuild and socket handling, armour events, and SQLite helpers used by TFMC plugins. Run build commands from the `tlibs` source checkout.
+TLibs provides shared item and block APIs, MMOItems rebuild and socket handling, armour events, inventory scanning, and SQLite helpers used by TFMC plugins. Run build commands from the `tlibs` source checkout.
 
 TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
 
@@ -47,3 +47,7 @@ Pinned mode installs the versions declared in the consumer POM. Use
 `--mode latest` when intentionally upgrading those dependencies, then review
 and commit the POM changes. Release provenance records the exact source and
 build inputs. TLibs remains a separate server plugin.
+
+## Shared feature ownership
+
+See [feature ownership and manual updates](../TFMCCore/ownership.md) for scanner, focus and letter APIs and the manual dev/main update steps.