feat(contracts): add server-side contract browser and progress tracking

docs/PROJECT.md

@@ -75,9 +75,25 @@ Behavior:
 
 Admins can also grant a tracker compass directly with `/souls tracker give <player> <target>`. This uses the same tracker data and duration as the kill-granted version.
 
+### Contracts
+
+Contracts let players earn souls without PvP by completing mining and hunting goals.
+
+Behavior:
+
+- Players pick one active contract at a time.
+- Mining contracts track block breaks against a configured block id.
+- Hunting contracts track kills against a configured entity id.
+- The selected contract and its progress appear in the HUD sidebar.
+- Completing a contract pays souls automatically.
+- The contract browser uses `catalog.yml`, where the YAML key is the internal contract id and `name` is the player-facing label.
+
 Implemented by:
 
-- [`TrackerCompassService`](../src/main/java/com/g2806/soulsteal/service/TrackerCompassService.java)
+- [`ContractService`](../src/main/java/com/g2806/soulsteal/service/ContractService.java)
+- [`ContractGuiService`](../src/main/java/com/g2806/soulsteal/contract/ContractGuiService.java)
+- [`ContractCatalog`](../src/main/java/com/g2806/soulsteal/contract/ContractCatalog.java)
+- [`ContractDefinition`](../src/main/java/com/g2806/soulsteal/contract/ContractDefinition.java)
 
 ### Shop
 
@@ -161,6 +177,12 @@ The root command has two aliases:
   - Shows leaderboard pages.
 - `/souls tracker give <player> <target>`
   - Gives a tracker compass to one player that points at another player.
+- `/souls contracts`
+  - Opens the contract browser GUI.
+- `/souls contracts selected`
+  - Shows the currently selected contract and progress.
+- `/souls contracts clear`
+  - Clears your selected contract.
 
 ### Admin Commands
 
@@ -205,6 +227,20 @@ Shop catalog definition. It controls:
 
 The catalog is loaded through [`ConfigBundle`](../src/main/java/com/g2806/soulsteal/config/ConfigBundle.java).
 
+### `config/soulsteal/catalog.yml`
+
+Contract catalog definition. It controls:
+
+- Contract categories by type
+- Internal contract ids from the YAML keys
+- Player-facing contract names
+- Icon item ids
+- Target block or mob ids
+- Required amounts and rewards
+- Repeatable behavior
+
+The catalog is loaded through [`ConfigBundle`](../src/main/java/com/g2806/soulsteal/config/ConfigBundle.java).
+
 ### `config/soulsteal/soulsteal-data.json`
 
 Persistent runtime data. It stores:
@@ -217,6 +253,8 @@ Persistent runtime data. It stores:
 - Permission fallback grants
 - Player name history
 - Scoreboard visibility preferences
+- Selected contracts
+- Contract progress
 
 Loaded and saved by [`SoulStealDataStore`](../src/main/java/com/g2806/soulsteal/data/SoulStealDataStore.java).
 
@@ -237,6 +275,13 @@ When one player kills another player:
 1. The killer receives kill reward souls if enabled.
 2. Any matching bounties on the victim are claimed.
 3. The killer receives a tracker compass if the tracker feature is enabled.
+4. Any matching hunting contract progresses if the killer has one selected.
+
+### Block Break
+
+When a player breaks a block:
+
+1. Any matching mining contract progresses if the player has one selected.
 
 ### Player Death
 
@@ -263,6 +308,8 @@ On shutdown:
 
 - `src/main/java/com/g2806/soulsteal/`
   - Bootstrap, commands, services, config, data, shop, and utilities.
+- `src/main/java/com/g2806/soulsteal/contract/`
+  - Contract catalog, GUI, and screen handling classes.
 - `src/main/resources/`
   - Fabric metadata and resource files.
 - `build.gradle`
@@ -274,3 +321,4 @@ On shutdown:
 - It is structured as a server-only feature set, so most behavior is driven by server lifecycle events.
 - Persistence is intentionally simple: one JSON data file and YAML-driven configuration.
 - External integrations are reflected through reflection-based checks so the mod can run without hard dependencies on permission backends.
+- Contract configuration is separated into `catalog.yml` so contract entries can be expanded without changing the main economy config.