Document the Patreon supporter integration

projects/ProvinceSystem/docs/README.md

@@ -15,6 +15,7 @@ This section is the product and technical reference for **ProvinceSystem**. Tech
    - [cosmetics/drinks.md](cosmetics/drinks.md) - BreweryX drink builder
    - [characters/creator.md](characters/creator.md) - web character creator
    - [identity/tfmcweb.md](identity/tfmcweb.md) - Discord link, tokens, gate
+   - [integrations/patreon.md](integrations/patreon.md) - Patreon supporter linking, entitlement and operations
 3. [flows/journeys.md](flows/journeys.md) - end-to-end player and staff journeys
 4. [ops/local-dev.md](ops/local-dev.md) - run the site locally
 5. [ops/sheet-render.md](ops/sheet-render.md) - 3D review-sheet renderer (prod deploy + smoke)
@@ -27,13 +28,13 @@ Schema assets: [assets/map-export-schema.json](assets/map-export-schema.json) (S
 | Component | Path | Role | Docs |
 |-----------|------|------|------|
 | **ProvinceSystem** | `ProvinceSystem/` | Website + FastAPI: maps, skins, drinks, characters, identity | This folder |
-| **TFMCWeb** | `tfmcweb/` | MC ↔ web gate: Discord link, scoped tokens, Survival Discord freeze, warn/ban mirror | [identity/tfmcweb.md](identity/tfmcweb.md) |
+| **TFMCWeb** | `tfmcweb/` | MC ↔ web gate: Discord link, scoped tokens, Survival Discord freeze, warn/ban mirror, Patreon rank writer | [identity/tfmcweb.md](identity/tfmcweb.md), [integrations/patreon.md](integrations/patreon.md) |
 | **SimpleFactions** | `simplefactions/` | Map bridge: nation JSON upload, queue, regen, province lookup | [integrations/simplefactions.md](integrations/simplefactions.md) |
 | **ArmourShop** | `armourshop/` | Skins pack writer + apply | [integrations/armourshop.md](integrations/armourshop.md) |
 | **DrinkBuilder** | `drinkbuilder/` | Donator BreweryX drinks + `tfmc_drinks` IA | [cosmetics/drinks.md](cosmetics/drinks.md) |
 | **RPCharacters** | `rpcharacters/` | Characters + freeze loop; Discord gate via freeze reason | [characters/creator.md](characters/creator.md) |
 | **ItemsAdder** | Server `plugins/ItemsAdder/` | Resource packs: `tfmc_submissions`, `tfmc_armorshop`, `tfmc_drinks` | [integrations/armourshop.md](integrations/armourshop.md) |
-| **tfmc_bot** | `tfmc_bot/` | Red-DiscordBot: skins/drinks review, link, ban/warn DMs | [integrations/discord-bot.md](integrations/discord-bot.md) |
+| **tfmc_bot** | `tfmc_bot/` | Red-DiscordBot: skins/drinks review, link, ban/warn DMs, Patreon supporter roles | [integrations/discord-bot.md](integrations/discord-bot.md), [integrations/patreon.md](integrations/patreon.md) |
 
 ## Locked platform decisions
 

projects/ProvinceSystem/docs/architecture.md

@@ -175,6 +175,7 @@ No website passwords. Codes are **not shareable by design**: cosmetics are grant
 | Map SF ↔ API ↔ web | [integrations/simplefactions.md](integrations/simplefactions.md) |
 | ArmourShop + `tfmc_submissions` | [integrations/armourshop.md](integrations/armourshop.md) |
 | tfmc_bot skins + ban role | [integrations/discord-bot.md](integrations/discord-bot.md) |
+| Patreon supporter roles + ranks | [integrations/patreon.md](integrations/patreon.md) |
 | Full journeys | [flows/journeys.md](flows/journeys.md) |
 | Naming | [cosmetics/naming.md](cosmetics/naming.md) |
 | TFMCWeb identity | [identity/tfmcweb.md](identity/tfmcweb.md) |

projects/ProvinceSystem/docs/identity/tfmcweb.md

@@ -4,7 +4,7 @@
 
 **Repos:** `tfmcweb/` (Bukkit plugin; depends on TLibs, soft-depends on Essentials) · `ProvinceSystem` · `tfmc_bot` · consumers `rpcharacters`, `armourshop`, `drinkbuilder` (depend) and `simplefactions` (soft-depend)
 
-Companion: [integrations/discord-bot.md](../integrations/discord-bot.md) · [cosmetics/skins.md](../cosmetics/skins.md)
+Companion: [integrations/discord-bot.md](../integrations/discord-bot.md) · [integrations/patreon.md](../integrations/patreon.md) · [cosmetics/skins.md](../cosmetics/skins.md)
 
 ## Why
 
@@ -24,6 +24,7 @@ Companion: [integrations/discord-bot.md](../integrations/discord-bot.md) · [cos
 | Freeze | **RPCharacters** freeze reason `DISCORD_REQUIRED`; do not touch characters |
 | Bans | Essentials `/tempban` / `/ban`; TFMCWeb mirrors to Discord bot |
 | Warnings | `/warning` (TFMCWeb) → player chat + web store + bot DM |
+| Patreon linking and status | `/patreon` (TFMCWeb) starts a link for an unlinked player, displays status, and `/patreon unlink` disconnects the link; backend-owned entitlement and rank application are documented in [Patreon integration](../integrations/patreon.md) |
 
 ## Ownership matrix
 
@@ -38,6 +39,7 @@ Companion: [integrations/discord-bot.md](../integrations/discord-bot.md) · [cos
 | Character ingest / roster | RPCharacters (HTTP via TFMCWeb gateway) |
 | Essentials ban/unban | Essentials executes; TFMCWeb mirrors |
 | Discord DMs / banned role / leave events | `tfmc_bot` |
+| Patreon LuckPerms groups | TFMCWeb rank writer on exactly one configured server; [Patreon integration](../integrations/patreon.md) |
 
 Domain plugins **depend on TFMCWeb** for network/identity. They do not open raw HTTP to ProvinceSystem.
 
@@ -148,6 +150,8 @@ Bot does **not** execute MC bans.
 | `/unlinkdiscord` | Explicit unlink |
 | `/token create skin\|drink\|profile` | Scoped code |
 | `/token resetcooldowns <player>` | Clear shared skin+drink mint cooldown |
+| `/patreon` | Show Patreon status; if unlinked, start account authorization |
+| `/patreon unlink` | Unlink the Patreon account |
 
 ### Staff
 
@@ -159,6 +163,24 @@ Bot does **not** execute MC bans.
 | `/web unlink <player>` | Force unlink |
 | `/warning <player> <reason>` | Warn + mirror |
 
+### Patreon rank writer
+
+TFMCWeb reads the `patreon:` block in `config.yml`:
+
+```yaml
+patreon:
+  enabled: false
+  apply-ranks: false
+  poll-seconds: 60
+  reconcile-minutes: 30
+  groups:
+    noble: noble
+    gilded: gilded
+    ascended: ascended
+```
+
+Set `apply-ranks: true` on exactly one server because LuckPerms storage is shared. Other servers keep it false. `/patreon` remains available wherever `enabled` is true. See [the Patreon integration guide](../integrations/patreon.md) for operations.
+
 ## Realm gateway
 
 Per-realm HTTP gateway, `rpc_player_meta` sync, realm-scoped token policy, and scoped data queues are **shipped**. Map staff permission `tfmc.map.staff` arrives via player meta for staff map and editor gates.

projects/ProvinceSystem/docs/integrations/discord-bot.md

@@ -13,6 +13,7 @@
 | Link | `/linkdiscord <code>` completes MC ↔ Discord bind |
 | Moderation | Ban/warn DMs, **Banned** role add/clear, guild leave/join for 1h grace |
 | Precedent | `/case-log` (staff) logs a case, `/precedent <info>` (staff+helper) searches precedent — see [precedent.md](precedent.md) |
+| Patreon | `patreon` cog - supporter link/status/unlink, role outbox, DMs, staff lookup and sync tools — see [patreon.md](patreon.md) |
 
 The bot does **not** execute in-game bans (Essentials owns MC bans).