inventory

docs/playable-slices/0.8.5-Reputation-Gated-Merchant-Offers.md

@@ -0,0 +1,247 @@
+# Ashen Realms – Playable Slice 0.8.5
+
+## Reputation-Gated Merchant Offers
+
+**Status:** Implementation Specification  
+**Depends on:** Slice 0.8  
+**Purpose:** Make reputation visible and useful by locking selected merchant offers behind reputation or explicit unlock conditions instead of character levels.
+
+---
+
+## 1. Goal
+
+The reputation system must change what the player can do.
+
+A merchant should be able to communicate:
+
+> "I don't know you well enough for that."
+
+or:
+
+> "Earn more trust in the Ashen Fields first."
+
+The player sees desirable locked items, understands the requirement, and has a reason to continue hunting and trading.
+
+---
+
+## 2. No Level-Gated Merchant Progression
+
+New merchant offers must not use character level as the primary progression gate.
+
+Preferred gates:
+
+- regional reputation
+- World Renown
+- NPC reputation, if already supported
+- quest/unlock flag
+
+The server is authoritative for all purchase requirements.
+
+If `requiredLevel` still exists in an old item schema, it may remain for compatibility, but new Tier-1 merchant progression in these slices should not rely on it.
+
+---
+
+## 3. Offer Requirement Model
+
+Merchant offers should support an optional requirement definition.
+
+Conceptual examples:
+
+```text
+NONE
+REGION_REPUTATION
+WORLD_RENOWN
+NPC_REPUTATION
+QUEST_FLAG
+```
+
+An offer may later support multiple requirements, but do not overbuild a general rule engine unless the current code already has one.
+
+A pragmatic structure is enough:
+
+```text
+requiredRegionReputation
+requiredWorldRenown
+requiredNpcReputation
+requiredUnlockFlag
+```
+
+with nullable values.
+
+---
+
+## 4. Initial Locked Offers
+
+At least two useful offers should demonstrate the system.
+
+Recommended examples:
+
+### Basic Hide Bag
+
+- important progression item
+- may be normally reputation-gated
+- Slice 0.9 can temporarily bypass the gate through a quest referral
+
+### Basic Trophy Pouch
+
+- unlocked after the player has demonstrated some regional reputation
+
+Optional additional offer:
+
+### Bandit Blade or another Tier-1 gap filler
+
+- available at a higher reputation threshold
+
+Exact thresholds are balancing data.
+
+---
+
+## 5. Visible Locked Offers
+
+Locked offers should usually remain visible.
+
+Example:
+
+```text
+Basic Trophy Pouch
+Capacity: 5 Raider Trophies
+Price: 40 Silver
+Requires: Ashen Fields Reputation 25
+Current: 14
+```
+
+The Buy action is disabled.
+
+This is preferable to hiding every locked item, because visible rewards create goals.
+
+---
+
+## 6. Server Validation
+
+A malicious client must not bypass a disabled button.
+
+Purchase flow:
+
+```text
+load character
+load merchant offer
+validate price
+validate reputation requirement
+validate quest/unlock flag
+validate inventory/bag ownership rules
+remove currency
+grant item/bag
+commit
+```
+
+If reputation is insufficient, return a stable domain error such as:
+
+```text
+MERCHANT_REPUTATION_TOO_LOW
+```
+
+with an English player-facing message.
+
+---
+
+## 7. Referral / Exception Support
+
+Slice 0.9 needs a special tutorial moment:
+
+The merchant normally would not give the player a useful bag yet, but a gate NPC sends the player with a referral.
+
+Therefore the offer/unlock system must support one minimal exception:
+
+```text
+requiredUnlockFlag = referred-by-south-gate-warden
+```
+
+or an equivalent quest reward/grant path.
+
+Do not implement a complex faction favor engine.
+
+The requirement is simply that the quest can legally allow one specific acquisition that reputation alone would not yet allow.
+
+---
+
+## 8. UI Requirements
+
+Merchant cards/rows show:
+
+- item/bag name
+- icon
+- Silver price
+- relevant effect
+- requirement
+- player's current value
+- locked/unlocked state
+
+Use clear English copy.
+
+Examples:
+
+```text
+Requires Ashen Fields Reputation 25
+```
+
+```text
+Requires World Renown 3
+```
+
+```text
+Unavailable – Borin does not know you well enough.
+```
+
+---
+
+## 9. Feedback on Unlock
+
+When a reputation increase makes an offer newly available, the player should receive lightweight feedback.
+
+Example:
+
+```text
+New merchant offer unlocked: Basic Trophy Pouch
+```
+
+No large modal is required.
+
+---
+
+## 10. Tests
+
+- offer with no requirement can be purchased
+- insufficient regional reputation blocks purchase
+- sufficient regional reputation allows purchase
+- insufficient World Renown blocks purchase
+- quest flag can unlock configured tutorial offer
+- disabled client state is not trusted by backend
+- price is still required even when reputation condition is met
+- unlock state changes after a successful trade-in raises reputation
+
+---
+
+## 11. Acceptance Criteria
+
+- [ ] Merchant offers can define reputation/unlock requirements.
+- [ ] At least two offers visibly demonstrate locked states.
+- [ ] Requirements are shown to the player in English.
+- [ ] Server rejects purchases when requirements are not met.
+- [ ] New progression offers do not depend on level gates.
+- [ ] Quest/referral unlock support exists for Slice 0.9.
+- [ ] Reputation increase can visibly unlock a previously locked offer.
+- [ ] No generalized rules engine was added unnecessarily.
+
+---
+
+## 12. Out of Scope
+
+Do not implement:
+
+- dynamic merchant personalities
+- haggling
+- randomized daily shops
+- faction wars
+- reputation decay
+- negative reputation systems
+- multiple currencies per individual offer unless already required