added more documentation

AGENTS.md

@@ -61,7 +61,6 @@ ShaiBot/
 │   └── poker/
 ├── utils/
 ├── index.js
-├── COOKIE_LOGIC.md
 ├── README.md
 ├── package.json
 └── .env                # never commit
@@ -504,7 +503,7 @@ Preserve this metadata because achievements/social relationship tracking depend
 
 Normal player-to-player stealing is separate from Vault Heist.
 
-The current steal model is documented in `COOKIE_LOGIC.md`.
+The current steal model is documented in `docs/ECONOMY.md`.
 
 Key current balance values:
 
@@ -2046,7 +2045,7 @@ Before modifying code:
 
 1. Read this file.
 2. Read `README.md`.
-3. If touching Cookies/steal logic, read `COOKIE_LOGIC.md`.
+3. If touching Cookie balances, transfers, stealing, cooldowns, settlement, or economy idempotency, read docs/ECONOMY.md.
 4. Read every utility directly involved.
 5. Read its command/button consumers.
 6. Search for imports/exports of functions being changed.
@@ -2097,19 +2096,24 @@ Use these docs together:
 
 ```text
 README.md
-    Broad feature/product overview and contribution conventions.
-
-COOKIE_LOGIC.md
-    Detailed /cookies steal/robbery rules and collection contracts.
+    Human-facing project overview, features, setup, and documentation index.
 
 AGENTS.md
-    Cross-repository AI-agent architectural/safety guide.
+    Repository-wide architecture, invariants, and safety rules for AI agents.
 
-Poker-specific agent guide (if present)
-    Deep Poker state/economy/rules/recovery contract.
+docs/ARCHITECTURE.md
+    Runtime, handlers, persistence, concurrency, and recovery.
 
-Phase/rollout notes (if retained)
-    Historical implementation context; current code still wins.
+docs/ECONOMY.md
+    Complete Cookie economy manual, including PvP stealing mechanics,
+    formulas, heat, exposure budgets, transfers, settlement, and idempotency.
+
+docs/GAMES.md
+    Crumb Saucer, Poker, Crumble Strike, and game mechanics.
+
+docs/PROGRESSION.md
+    Profiles, achievements, badges, activity, social progression,
+    reconciliation, and maintenance.
 ```
 
 If an older phase note disagrees with current implementation, do not regress current code to match the note.