added more documentation

docs/GAMES.md

@@ -0,0 +1,262 @@
+# ShaiBot Game Manual
+
+This document gives maintainers a compact overview of the main game
+systems. Exact rules remain in the owning utilities.
+
+# Crumb Saucer
+
+The Crumb Saucer is ShaiBot's Cookie-powered game hub.
+
+Shared principle:
+
+``` text
+Discord controls
+→ game utility
+→ Cookie economy / profile system
+```
+
+## Slots
+
+Core utility:
+
+``` text
+utils/crumbSlots.js
+```
+
+Features include multiple wagers, symbol payouts, jackpots, All-In
+tracking, Run It Back, profile statistics, achievements, and guild-first
+triplet badges.
+
+Historical replay facts must come from wager-time metadata rather than
+the player's current Cookie balance.
+
+## Blackjack
+
+Core utility:
+
+``` text
+utils/crumbBlackjack.js
+```
+
+Supports:
+
+-   Hit
+-   Stand
+-   Double
+-   Dealer stands on 17
+-   Natural Blackjack pays 3:2
+-   Push
+-   All-In
+-   Run It Back
+
+Repeated interactions must never resolve/pay the same hand twice.
+
+## Roulette
+
+Core utility:
+
+``` text
+utils/crumbRoulette.js
+```
+
+European Roulette uses `0–36`.
+
+Simple bets include Red, Black, Odd, Even, and Zero. Zero loses for
+Red/Black/Odd/Even.
+
+Animation uses edits of the same message rather than high-frequency
+message spam.
+
+## Vault Heist
+
+Core utility:
+
+``` text
+utils/cookieHeist.js
+```
+
+Vault Heist targets ShaiBot's house vault and is separate from PvP
+stealing.
+
+Approaches include Sneak, Hack, and Smash and share the same Heist
+cooldown.
+
+## Bankruptcy
+
+Core utility:
+
+``` text
+utils/bankruptcy.js
+```
+
+Bankruptcy provides a recovery path and tracks post-Bankruptcy
+rebuilding in profiles.
+
+Recovery progress should reflect actual balance after Bankruptcy, not
+merely lifetime Cookie gains.
+
+## Run It Back
+
+Supported games can track consecutive replay through the explicit Run It
+Back action.
+
+A normal/new wager breaks the chain.
+
+Win/loss/push does not inherently break it because the streak represents
+the player's decision to immediately replay.
+
+Historical All-In and wager state must be preserved at the time the
+wager occurs.
+
+# Poker
+
+Poker is a persistent 2--6 player Texas Hold'em game inside the Crumb
+Saucer.
+
+Important files:
+
+``` text
+utils/pokerEngine.js
+utils/crumbPoker.js
+utils/pokerDiscord.js
+utils/pokerInteractions.js
+utils/pokerProfile.js
+handlers/poker.js
+buttons/poker/*
+selectMenus/poker/*
+```
+
+Current defaults:
+
+``` text
+Buy-in:       1,000 Cookies
+Blinds:       10 / 20
+Turn timer:   90 seconds
+Pot model:    single pot
+```
+
+Supported actions:
+
+``` text
+Fold
+Check
+Call
+Bet
+Raise
+All-In
+```
+
+## Single-Pot Rule
+
+Poker intentionally has no side pots.
+
+At hand start, the maximum amount each participant can commit is limited
+by the smallest participating starting stack.
+
+Chips above that cap remain protected for a later hand.
+
+## Persistence
+
+MongoDB is authoritative for live/recoverable tables.
+
+Poker uses temporary state in:
+
+``` text
+items_special_games
+```
+
+and optimistic versioning for authoritative updates.
+
+Fully settled games are cleaned up rather than kept permanently as raw
+history.
+
+## Economy
+
+Cookies move only at buy-in and cash-out/refund boundaries.
+
+Betting moves internal table chips.
+
+Recovery-sensitive economy operations are idempotent.
+
+## Privacy
+
+Hole cards are private.
+
+The private Cards view may show the requesting player's cards, community
+cards, turn status, and remaining turn time.
+
+It must never expose opponent cards.
+
+A player-facing equity/win-percentage calculator is intentionally
+excluded from V1 for fairness.
+
+## Turn / Lobby Behavior
+
+Active turns have a 90-second deadline.
+
+Timeout folding uses the same authoritative Fold transition as a normal
+player action.
+
+Lobby expiry is disabled while a hand is active and refreshed when a
+hand ends.
+
+The internal between-hand state may be called `NEXT_HAND`, but the
+user-facing UI presents **HAND COMPLETE**.
+
+## Cancellation / Cleanup
+
+Host cancellation is allowed outside an active hand.
+
+Cancellation safely settles players before deleting the table state.
+
+Confirmation controls should disappear after Confirm or Keep so stale
+buttons cannot remain usable.
+
+# Crumble Strike
+
+Core utility:
+
+``` text
+utils/crumbleStrike.js
+```
+
+Crumble Strike is a persistent cooperative boss battle.
+
+Typical flow:
+
+1.  Spawn encounter.
+2.  Recruit players.
+3.  Start once requirements are met.
+4.  Fight within the encounter lifetime.
+5.  Settle success/failure and committed Cookies.
+
+Combat includes:
+
+``` text
+Strike
+Defend
+Heal
+Revive
+Limit Break
+```
+
+Roles include:
+
+``` text
+DPS
+Tank
+Healer
+```
+
+Crumble Strike has more lifecycle complexity than ordinary Saucer games.
+Do not copy its persistence model into simpler games unless the new
+feature genuinely requires it.
+
+# Raid Planner
+
+Raid planning uses Discord embeds and reactions.
+
+Participation can count unique users across reactions without forcibly
+removing reactions.
+
+Be mindful of Discord partials when changing reaction behavior.