From 4e2a95503e4ea4c830510f5aea23fac7948ddc41 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Thu, 1 Oct 2026 17:24:54 -0400
Subject: feat: set and autoset in pai gow, better showdown arrangement, better
 formatting

---
 dev_guide/pai_gow.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

(limited to 'dev_guide')

diff --git a/dev_guide/pai_gow.md b/dev_guide/pai_gow.md
index dd4cd7d..3e0bc88 100644
--- a/dev_guide/pai_gow.md
+++ b/dev_guide/pai_gow.md
@@ -33,6 +33,32 @@ seat and re-checks `allBetLocked` so the remaining bettors can be dealt.
 The Push Ace High cap (half the main wager) is enforced when the main wager
 lands, because side bets are already down by then.
 
+## Player setting and showdown
+
+An arrangement made with `24`/`13456`/`house` is stored on the player as
+`pending`; it does not lock the hand or reveal the dealer. `set` moves
+`pending` into `split` and marks the seat ready. When `autoset` is on (the
+table default or a per-seat `autoset on`) a legal arrangement is committed
+straight to `split`. A seat's `autoset` is seeded from
+`PaiGowConfig.Autoset` at join.
+
+When every active seat is ready, `prepareSettlementLocked` evaluates both
+sides, builds a `PaiGowShowdown`, and hands it to `payLocked`. The showdown
+always orders `Hands` player-high, dealer-high, player-low, dealer-low.
+Each `PaiGowHandView` carries the label, the `pgRankName` strength, the
+cards, and whether that hand won its comparison. The presentation layer
+derives the colours (bold yellow for a winning strength, bold white for a
+losing one) from those flags, so the casino package stays colour-free. The
+`PaiGowShowdown` also carries the main result word, Fortune and Push Ace
+outcomes, the Envy amount (only when another active player is seated), the
+total stake, the payout, and the paid/pending state.
+
+The dealt seven cards are only put on the snapshot before a seat has
+arranged anything. A manual seat shows its `pending`/committed split as the
+`Preview` (high then low, gap between, position numbers); an autoset seat
+skips the preview and shows only the set/waiting note. `pgCardNums` maps
+each hand card back to its 1-7 dealt position.
+
 ## House way
 
 This is a **local, deterministic house way**, not a claim to reproduce a
-- 
cgit v1.2.3