Merge pull request 'docs: economy v0.4 — 13-tier ladder + Sovereign 10M + Founder flag' (#64) from docs/economy-v0.4-13-tier-ladder into main

docs/economy-system.md

@@ -1,6 +1,6 @@
 # Brass and Sigil — Economy & Quest System Design
 
-> Status: architecture + UI approach locked (v0.3). Custom companion mod confirmed.
+> Status: 13-tier ladder locked (v0.4). Architecture + UI confirmed in v0.3.
 > Owner: matt
 > Last updated: 2026-06-06
 
@@ -81,19 +81,36 @@ Two distinct land/status systems that often get conflated. Keeping them clean:
 
 Every player has a Civic rank. Higher rank unlocks perks. Players spend spurs at the Civic Office NPC to upgrade. Powered by FTB Ranks under the hood (permission nodes drive what each rank unlocks).
 
-| # | Title | Cost to reach | Wilderness chunks claimable | Spawn plot slots | Sethomes | Daily bounty slots | Shop fee | Chat colour | Join broadcast | `/back` after death |
+The ladder is intentionally long (13 tiers) so endgame ranks feel rare and aspirational. Top tiers represent months of dedicated play; Sovereign is "you've finished the game."
+
+| # | Title | Cost to reach | Wilderness chunks | Plot slots | Sethomes | Daily bounties | Shop fee | Chat colour | Join broadcast | `/back` |
 |---|---|---|---|---|---|---|---|---|---|---|
-| 1 | **Peasant** | free (starter) | 9 | 0 | 1 | 3 | -0% | grey | no | no |
+| 1  | **Peasant**     | free (starter)  | 9     | 0  | 1         | 3  | 0%    | grey       | —             | — |
-| 2 | **Citizen** | 500 | 25 | 1 | 2 | 3 | -0% | white | no | no |
+| 2  | **Farmer**      | 200             | 18    | 0  | 1         | 3  | 0%    | grey       | —             | — |
-| 3 | **Patron** | 2,000 | 60 | 1 | 3 | 4 | -2% | yellow | no | yes |
+| 3  | **Citizen**     | 750             | 35    | 1  | 2         | 3  | 0%    | white      | —             | — |
-| 4 | **Notable** | 6,000 | 100 | 2 | 4 | 4 | -5% | green | simple | yes |
+| 4  | **Merchant**    | 2,500           | 60    | 1  | 3         | 4  | -2%   | yellow     | —             | ✓ |
-| 5 | **Baron** | 15,000 | 160 | 2 | 5 | 5 | -8% | cyan | simple | yes |
+| 5  | **Knight**      | 6,500           | 100   | 2  | 4         | 4  | -5%   | green      | simple        | ✓ |
-| 6 | **Noble** | 35,000 | 240 | 3 | 7 | 5 | -10% | purple | fancy | yes |
+| 6  | **Baron**       | 15,000          | 150   | 2  | 5         | 5  | -7%   | cyan       | simple        | ✓ |
-| 7 | **Lord** | 80,000 | 350 | 4 | 10 | 6 | -12% | gold | fancy | yes |
+| 7  | **Viscount**    | 35,000          | 220   | 3  | 6         | 5  | -9%   | blue       | fancy         | ✓ |
-| 8 | **Sovereign** | 200,000 | 500 | 5 | unlimited | 6 | -15% | red | epic | yes |
+| 8  | **Earl**        | 75,000          | 300   | 3  | 8         | 6  | -11%  | purple     | fancy         | ✓ |
+| 9  | **Marquess**    | 150,000         | 400   | 4  | 10        | 6  | -13%  | gold       | fancy         | ✓ |
+| 10 | **Duke**        | 300,000         | 525   | 5  | 12        | 7  | -15%  | orange     | epic          | ✓ |
+| 11 | **Archduke**    | 700,000         | 700   | 6  | 16        | 7  | -17%  | red        | epic          | ✓ |
+| 12 | **Grand Duke**  | 1,500,000       | 900   | 7  | 20        | 8  | -19%  | bright red | epic + particles | ✓ |
+| 13 | **Sovereign**   | 10,000,000      | 1,500 | 10 | unlimited | 10 | -25%  | rainbow    | epic + spectacular | ✓ |
+
+**Notable shape choices:**
+
+- **Knight (tier 5)** is the gentry threshold — first colored chat (green), first join broadcast, first `/back` after a meaningful jump in plot slots
+- **Duke → Archduke jump** is the late-game wall (300k → 700k, ~2.3×) — Archduke is the start of "I've really committed to this server" territory
+- **Sovereign is dramatic** — 6.7× the Grand Duke cost. Real "finished the game" status. -25% shop fee is a step-change leap; unlimited everything; spectacular join effects.
 
 Numbers are first-pass calibration. The full perk table lives in a single JSON (`config/bnstoolkit/tiers.json`) that's hot-reloadable via `/bnstoolkit reload`. Easy to tune any column without code changes.
 
+### 4a.1 Founder flag (admin cosmetic)
+
+The server owner / admin has a permanent **`[Founder]`** cosmetic prefix in chat that sits alongside their normal rank. It carries no gameplay perks — it's just visible identification so friends know who runs the server. The Founder still grinds the regular tier ladder like everyone else (good for playtesting balance + sharing the experience). Op commands are the actual admin tool; the Founder tag is purely visual.
+
 **Wilderness claims:** at every tier above Peasant, you get a flat allowance of N chunks you can claim anywhere outside spawn via the FTB Chunks map. Claiming is **free** within your allowance, refused above. No per-chunk pricing. Driven by FTB Ranks → FTB Chunks permission nodes (`ftbchunks.max_claimed_chunks`).
 
 ### 4b. Spawn plots
@@ -411,7 +428,8 @@ Resolved before implementation:
 | Numismatics access | Direct Java via `Java.loadClass` from KubeJS; via API directly from the mod |
 | Wilderness chunk allowance | Tier-driven via FTB Ranks permission nodes — no per-chunk pricing |
 | Spawn plots | Predefined regions, slot-limited by tier, individually purchased with spurs |
-| Tier ladder | Civic: Peasant → Citizen → Patron → Notable → Baron → Noble → Lord → Sovereign (8 tiers) |
+| Tier ladder | Civic (13 tiers): Peasant → Farmer → Citizen → Merchant → Knight → Baron → Viscount → Earl → Marquess → Duke → Archduke → Grand Duke → Sovereign |
+| Founder flag | Admin/owner has `[Founder]` cosmetic prefix in chat, grinds the regular ladder otherwise |
 | Tier perks | JSON-configured (`config/bnstoolkit/tiers.json`), hot-reloadable |
 | Custom mod | Confirmed. Built on FTB Library UI framework. Working name `bnstoolkit`. |
 | Sethomes / warps | Tier-allocated count (not paid per use) |