added more documentation

docs/ECONOMY.md

@@ -0,0 +1,168 @@
+# ShaiBot Cookie Economy
+
+This manual describes the shared Cookie economy and the rules
+maintainers should preserve.
+
+## Source of Truth
+
+`utils/cookieEconomy.js` is the shared economy utility.
+
+Game and command modules should not perform independent ad-hoc balance
+mutations when the shared economy already provides the required
+operation.
+
+## Balances
+
+Cookie balances live in:
+
+``` text
+items_cookies
+```
+
+Conceptually:
+
+``` js
+{
+    userId: "...",
+    cookies: 2500
+}
+```
+
+Negative changes use an atomic balance filter so a player cannot spend
+more Cookies than are available.
+
+Expected insufficient-balance failures use:
+
+``` text
+INSUFFICIENT_COOKIES
+```
+
+Some subsystems carry expected error identifiers in `error.message`,
+while others may also use `error.code`. User-facing formatters should
+account for the convention used by that subsystem.
+
+## Transfers
+
+Player-to-player transfers do not require MongoDB transactions.
+
+The safe conceptual sequence is:
+
+``` text
+atomic debit source
+→ credit destination
+→ compensate source if destination credit fails
+```
+
+A critical compensation failure must remain visible in logs.
+
+## Cooldowns
+
+Cooldowns live in:
+
+``` text
+cooldown_cookies
+```
+
+Use the shared cooldown helpers, especially atomic cooldown claiming
+when double-clicks or simultaneous requests must not both succeed.
+
+## House Vault
+
+ShaiBot acts as the general house Cookie vault for supported games.
+
+Gambling losses and penalties may feed the vault, while wins, heists,
+and rewards may pay out from it.
+
+House-funded features should respect their existing liquidity rules.
+
+## Cookie Collection
+
+`/cookies collect` and the Crumb Saucer Bakery share
+`utils/crumbCollect.js`.
+
+They must share:
+
+-   the same cooldown
+-   the same reward generation
+-   the same balance mutation
+-   the same profile tracking
+
+Do not create separate collection behavior for the two interfaces.
+
+## PvP Stealing
+
+Normal player-to-player stealing is separate from Vault Heist.
+
+Detailed robbery balancing lives in:
+
+``` text
+COOKIE_LOGIC.md
+```
+
+The current model includes wealth scaling, victim heat, percentage-based
+loot, a hard per-hit cap, and an hourly victim exposure budget.
+
+## Persistent Game Settlement
+
+For simple house games, settlement should still be protected against
+repeated resolution.
+
+For lifecycle-heavy multiplayer games such as Poker, Cookie movement is
+separated from internal chip movement.
+
+Poker only crosses the Cookie economy boundary for:
+
+``` text
+buy-in
+cash-out / refund
+```
+
+Ordinary Poker betting modifies the table's internal stack state, not
+`items_cookies`.
+
+## Idempotent Operations
+
+Recovery-sensitive economy flows can use operation IDs.
+
+Poker temporarily stores markers such as:
+
+``` js
+appliedCookieOperations: [
+    "poker_buyin:...",
+    "poker_cashout:..."
+]
+```
+
+The purpose is to prevent a retry after a crash from moving money twice.
+
+Safe lifecycle:
+
+``` text
+apply Cookie operation once
+→ persist authoritative game state
+→ confirm operation is durably represented
+→ remove temporary marker
+```
+
+Never remove a recovery marker before the surrounding state is safe.
+
+When the final marker is removed, unset the empty field instead of
+leaving:
+
+``` js
+appliedCookieOperations: []
+```
+
+## Economy Invariants
+
+Every economy change should preserve:
+
+``` text
+No Cookie duplication.
+No unexplained Cookie loss.
+No duplicate debit.
+No duplicate payout.
+No spending below zero.
+```
+
+Correctness and recoverability take priority over cosmetic cleanup.