Merge pull request 'docs: quest tracking + cancel UX' (#61) from docs/economy-quest-tracking into main

Three-layer visibility plan:
  V1 (Phase 3): /quests, /quests info, /quests cancel commands.
                Mobile-friendly via the bridge, no extra mods.
  V2 (Phase 3.5): Quest Log book item with dynamic pages.
  V3 (later): optional sidebar HUD via vanilla scoreboards.

3-slot active-quest cap so cancellation is a real choice:
  - Prevents accept-all-then-cancel-easy-ones RNG shopping
  - Keeps state files small
  - READY frees the slot so turn-in backlogs are workable

State storage schema documented (active + completed/cooldown).

Phase 3.5 added to the roadmap for the book item.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/economy-system.md

@@ -120,12 +120,62 @@ The same accept → complete → return pattern works for every guild:
 | **Library** | "Recover this lost tome" | find the book in a structure | NPC pays + grants reputation |
 | **Foundry** | "Craft 10 Andesite Casings" | craft them | NPC pays commission |
 
+### Player-facing tracking & cancellation
+
+A quest engine that players can't inspect is worthless. The design ships with three layers of visibility:
+
+#### V1 — command-driven (Phase 3, with the engine)
+
+| Command | Effect |
+|---|---|
+| `/quests` | Lists all of your ACTIVE and READY quests with progress, source guild, and reward |
+| `/quests info <id>` | Detail view for one quest — description, objective, progress, reward |
+| `/quests cancel <id>` | Drops an active quest, freeing your slot. The quest goes on cooldown as if completed (prevents accept-cancel-accept RNG farming) |
+
+Cheap to ship. Works on mobile via the Telegram bridge. Doesn't require any extra mods.
+
+#### V2 — Quest Log book item (Phase 3.5)
+
+Every new player joins with a **Quest Log** book in their inventory (KubeJS `PlayerEvents.loggedIn` grants it once). Right-click to open. Dynamic Patchouli-style pages list active/ready quests, with a "Cancel" button per quest. Same backend as the `/quests` commands — just a nicer surface.
+
+#### V3 — Sidebar HUD (later)
+
+Optional scoreboard sidebar showing 2-3 most recent quests + progress, always-on. Implemented via vanilla scoreboard objectives driven by KubeJS. Players can toggle on/off via `/quests sidebar`.
+
+### Quest slot limit
+
+Players have a **maximum of 3 active quests at a time.** This is the friction that makes cancel meaningful:
+
+- Forces players to pick which quests they actually want — no "accept all 5, see what's easiest, cancel the rest" RNG-shopping.
+- Keeps the state files small.
+- Makes ready-to-turn-in queues meaningful (you can hold 3 unrewarded quests in your back pocket).
+
+A quest moving to READY frees the slot for accepting a new one even before turn-in.
+
 ### KubeJS implementation sketch
 
-- **State storage:** per-player JSON in `world/data/bns_quests/<uuid>.json`, written via KubeJS persistent-data hooks.
+- **State storage:** per-player JSON in `world/data/bns_quests/<uuid>.json`, written via KubeJS persistent-data hooks. Schema:
+  ```json
+  {
+    "active": [
+      {
+        "id": "advg_plunderer_10",
+        "acceptedAt": 1717684800,
+        "progress": 7,
+        "target": 10,
+        "rewardSpurs": 50,
+        "source": "adventurers_guild"
+      }
+    ],
+    "completed": {
+      "advg_plunderer_10": { "cooldownUntil": 1717771200, "completions": 3 }
+    }
+  }
+  ```
 - **Event tracking:** standard KubeJS event handlers (`EntityEvents.death`, `ItemEvents.pickedUp`, `BlockEvents.broken`) read the player's active quests and increment.
 - **Dialog branching:** Easy NPC dialog with conditions that call KubeJS to check quest state and route the dialog appropriately.
 - **Reward delivery:** call Numismatics' wallet API to deposit spurs.
+- **Commands:** registered via `ServerEvents.commandRegistry` in KubeJS, scoped to the player who runs them.
 
 ---
 
@@ -217,7 +267,8 @@ Each phase is independently shippable. Earlier phases unlock value without depen
 | **0** | Spawn skeleton built — 7 guild buildings placed (rough). | Locations have to exist before NPCs can stand in them. |
 | **1** | **Merchant's Bazaar V1:** Numismatics sell shop (fixed prices, no DR yet) for diamonds & netherite. | Cheapest to ship, immediate economy unlock. |
 | **2** | **Civic Office V1:** Plot claim cost via KubeJS `/ftbchunks claim` override. | Real money sink. Tests FTB Chunks integration depth. |
-| **3** | **Adventurer's Guild V1:** Bounty board engine. 5 daily quests, accept→complete→return flow. | The biggest gameplay feature. Validates the universal quest pattern. |
+| **3** | **Adventurer's Guild V1:** Bounty board engine. 5 daily quests, accept→complete→return flow, `/quests` commands, 3-slot cap. | The biggest gameplay feature. Validates the universal quest pattern. |
+| **3.5** | Quest Log book item (V2 of tracking surface). | Nicer UX surface on top of the same engine — non-blocking. |
 | **4** | **Villager rebalance:** strip vanilla, ship the spur-priced trade table. | Closes the exploit. Big JSON pass. |
 | **5** | **Library / Academy:** FTB Quests anchor + first chapter of progression quests. | Long-form content begins. |
 | **6** | **Civic Office V2:** FTB Ranks integration + tier upgrades. | Endgame money sink. |