new: usr: add initialization bonus points' system to the gameplay #5

docs/README.md

@@ -0,0 +1,47 @@
+# Mine-Seeker Game Documentation
+
+This directory contains comprehensive documentation about the Mine-Seeker game mechanics and implementation.
+
+## Game Mechanics
+
+### [Bonus Points System](./game-mechanics/BONUS_POINTS_SYSTEM.md)
+Complete reference for the bonus points system including:
+- All 6 bonus point types (Blind Hit, Chain Combo, Edge Mine, Endgame Mine, Safe Cell Bonus, Biggest Reveal)
+- Calculation rules and examples
+- Bonus statistics tracking
+- Player name formatting in dialogs
+- Database schema
+- Implementation notes
+- Testing checklist
+
+**Recommended for**: Developers working on bonus system, AI assistants implementing or debugging bonus features, understanding game scoring mechanics.
+
+---
+
+## Quick Reference
+
+### Bonus Points at a Glance
+| Bonus Type | Points | Condition |
+|-----------|--------|-----------|
+| Blind Hit | +2 | Mine with no revealed numbered neighbors |
+| Edge Mine | +1 | Mine on board boundary (row/col 0 or 15) |
+| Endgame Mine | +3 | Mine clicked when ≤10 mines remain |
+| Safe Cell | +0.5 each | ≥2 safe cells revealed (min requirement) |
+| Chain Combo | Tracked | Consecutive mine clicks (no safe clicks) |
+| Biggest Reveal | Tracked | Largest number of safe cells revealed |
+
+### Key Rules
+- Safe cell bonus only awarded for ≥2 cells minimum
+- Chain counter resets on any safe cell click
+- Endgame threshold: 51 - (redPoints + bluePoints) ≤ 10
+- Bonus stats are per-player and persist in database
+
+---
+
+## Files Using This Information
+- Backend: `/src/Util/TopicManager.php`
+- Frontend: `/assets/js/mine-seeker/contexts/GameProvider.jsx`
+- UI: `/assets/js/mine-seeker/components/BonusStatsDialog.jsx`
+- Constants: `/assets/js/mine-seeker/utils/constants.jsx`
+
+