feat: pai gow poker added to the casino

1 files changed, 45 insertions, 0 deletions

diff --git a/dev_guide/video_poker.md b/dev_guide/video_poker.md
new file mode 100644
index 0000000..46d900e
--- /dev/null
+++ b/dev_guide/video_poker.md
@@ -0,0 +1,45 @@
+# Video poker internals
+
+Builder-facing cabinet configuration, payout tiers and player controls
+live in [../building_guide/video_poker.md](../building_guide/video_poker.md).
+This page covers presentation and money-safety internals.
+
+## Presentation
+
+Pay tables use yellow Unicode borders and dotted hand-name leaders. Blue
+`#000269`, red `#fe0000` (selected coin column), and yellow `#f7e70e` are mapped
+to nearest xterm colors. HELD and wins are bold yellow; no-win text is bold
+white. Results are below cards. Bonus indicators and multipliers sit beside
+cards. Multi-hand art shrinks; hundred-play uses compact Unicode ranks/suits.
+
+Payouts are total coins including stake, not profit. Multiply by denomination
+for credits. Natural royals pay 250 per coin below five coins, 4000 at five.
+Other categories scale linearly. Only the highest-paying category pays.
+All games use fresh 52-card decks except Joker Poker's 53-card deck. Each line
+shares the deal/holds but draws from its own shuffled remaining deck, excluding
+**all five** original cards, including discards.
+
+## Shared banks and money safety
+
+Ultimate X multipliers belong to the **machine**, not the player. Another
+occupant inherits them. Files live at
+`data/casino/video_poker_banks/<room>_<cabinet>.yaml`. Within each file banks
+are keyed by game/tier/denomination/hand-count, preventing denomination or
+edition switching from amplifying an award. Fully consumed banks are removed.
+Missing files are new machines; corrupt/unreadable files block deals.
+
+`casino.PokerWallet` loads banks and atomically settles character credits,
+pending stake removal, and the cabinet file in a multi-file undo-journal
+transaction. There is no package-global persistence callback. The game owner
+serializes writes. The stake is durable before revealing cards; frozen final
+hands and awards survive payment retries without redraws or rerolls. Failed
+transactions leave the old live bank intact. Commit-point failures are recovered
+and reconciled before any retry; unrecoverable storage faults fail closed.
+Startup journal recovery precedes pending-wager recovery. A process crash before
+commit restores both old records, then refunds the unresolved stake. Committed
+payouts cannot replay an old bank. Shutdown/eviction refunds unresolved stakes
+without consuming previously saved multipliers or retaining uncommitted awards.
+
+Old experimental player-owned `video_poker_multipliers` fields are no longer
+read. They are not merged into shared cabinets (multiple player banks cannot
+unambiguously become one physical bank).