feat: new casino game: coin flip

2 files changed, 36 insertions, 1 deletions

diff --git a/data/help/casino.yaml b/data/help/casino.yaml
index fe81bad..74b1250 100644
--- a/data/help/casino.yaml
+++ b/data/help/casino.yaml
@@ -1,7 +1,7 @@
 name: casino
 aliases: [play, bet, rebet, table, watch, rules]
 category: Interaction
-related: [big6, roulette, racetrack, blackjack, baccarat, craps, slots, video poker, pai gow poker, plinko, pachinko, cash hunt, predictions, crypto]
+related: [big6, roulette, racetrack, blackjack, baccarat, craps, slots, video poker, pai gow poker, plinko, pachinko, cash hunt, coin flip, predictions, crypto]
 description: |
   Casino quick guide
 
@@ -55,6 +55,7 @@ description: |
   help plinko        Animated pyramid, four risk levels, up to ten balls.
   help pachinko      Rectangle of pins; populated board; pick a top slot; DOUBLE chains prizes.
   help cash hunt     Reveal 100 prizes, mix their positions, pick one square.
+  help coin flip     Fair 50/50 coin; red 0 to -100x, blue 0 to +100x; reserves 100x the stake.
   help video poker   Five cabinet types, selectable games, toggle holds and bonuses.
   help pai gow poker Seven cards, two hands; Classic, EZ, No Push and Fortune/Envy.
 
diff --git a/data/help/coin_flip.yaml b/data/help/coin_flip.yaml
new file mode 100644
index 0000000..56d9dd0
--- /dev/null
+++ b/data/help/coin_flip.yaml
@@ -0,0 +1,34 @@
+name: coin flip
+aliases: [coinflip, coin_flip, coin-flip, coin]
+category: Interaction
+related: [casino, cash hunt, pachinko]
+description: |
+  COIN FLIP — a fair 50/50 coin with two spinning faces.
+
+  play coin flip             Take the single seat.
+  bet 10                     Stake 10 (the house reserves 1000); the faces spin.
+  bet / rebet                Repeat your last stake.
+  stop                       Leave after the coin has landed.
+
+  Each round the RED face spins like a wheel and lands a negative multiplier
+  from 0 to -100. The BLUE face then spins and lands a positive multiplier
+  from 0 to +100, with a middle band (63-77 and 90) removed so the two faces
+  still average a -2 swing. The landed multipliers print, then the fair
+  50/50 coin flips. A settled coin is filled in solid red or blue.
+
+  The multiplier is a NET swing on your stake, so red -50 loses half your
+  stake, blue +50 wins half your stake, red -100 loses it all, and blue +100
+  doubles it. Multipliers include the stake; +0x is a push.
+
+  Because the swing can reach 100x your stake, the house requires you to
+  hold 100x your stake and reserves exactly that when you bet. Your payout
+  is (100 + swing) x stake, so it is never negative: a -100 red simply
+  returns zero. The reserve and the payout are one settled transaction.
+
+  The coin is exactly fair. The 2% house edge comes from the two faces:
+  red is uniform over 0..100 and blue drops a middle band to a mean of +46,
+  so the two distributions average a -2 swing per stake — exactly 98% RTP.
+
+  You cannot leave mid-round. Shutdown refunds an unsettled round; a failed
+  payout keeps your stake pending for recovery and settle retries the same
+  landed face.