updated readme

README.md

@@ -1,35 +1,124 @@
 # ShaiBot
 
-A modular **Discord.js** bot with a shared Cookie economy, interactive
+A modular **Discord.js** bot built around a shared Cookie economy,
-Crumb Saucer games, cooperative boss battles, raid planning, and
+interactive Crumb Saucer games, player profiles, achievements, global
-community interactions.
+badges, cooperative boss battles, raid planning, and community
+interactions.
 
-> **Status:** Active development. Game balance and individual features
+> **Status:** Active development. Features, achievements, and game
-> may change.
+> balance may change.
 
 ## Features
 
 ### 🍪 Cookie Economy
 
 Cookies are ShaiBot's shared virtual currency. The economy supports
-persistent balances, atomic balance checks, transfers, per-user
+persistent balances, atomic balance checks, transfers, Mongo-backed
 cooldowns, and a shared bot/house vault.
 
 The bot itself acts as the general Cookie vault: gambling losses and
-penalties can feed the vault, while wins, heists, and rewards can pay
+penalties can feed the vault, while wins, heists, collection rewards,
-Cookies back out.
+and other systems can pay Cookies back out.
+
+Cookie collection is shared between `/cookies collect` and the **Crumb
+Saucer Cookie Bakery**, using the same cooldown and reward logic.
+
+### 👤 Player Profiles
+
+ShaiBot includes persistent player profiles that bring together Cookie
+and game activity.
+
+Profiles can expose:
+
+-   Cookie economy statistics
+-   Per-game statistics
+-   Lifetime gains and losses
+-   Stealing and giving activity
+-   Achievements
+-   Global badges
+-   Collection progress
+
+Profile menus are public so other members can view them, while
+interactive controls are intended to remain restricted to the session
+owner. Errors, cooldown/debug-style feedback, and unauthorized
+interaction messages may be ephemeral.
+
+### 🏆 Achievements
+
+Achievements are repeatable across the community: every eligible player
+can earn their own copy.
+
+Achievement tracking can use persistent profile statistics as well as
+explicit game events. Current and planned categories include:
+
+-   Cookie collection and economy milestones
+-   Giving and stealing milestones
+-   Game wins and losses
+-   Game-specific loss milestones
+-   All-In accomplishments
+-   Run It Back streaks
+-   Cross-game special challenges
+-   Collector achievements for earning a portion or all available
+    achievements
+
+Game-specific achievements use names such as:
+
+``` text
+The House Always Wins: Blackjack
+```
+
+where sharing a generalized achievement concept between games makes
+sense.
+
+### 🎖️ Global Badges
+
+Global badges are guild-wide collectibles that can have a single owner.
+They are intended for special "first player to..." accomplishments and
+other unique distinctions.
+
+Examples include:
+
+-   First-time game accomplishments
+-   Slots triplet combinations
+-   All-In / Run It Back feats
+-   Special or hidden manually awarded badges
+-   Achievement collection milestones
+
+Badges may be hidden until discovered. Some special badges are
+intentionally managed manually in MongoDB rather than automatically
+awarded by gameplay.
 
 ### 🎰 The Crumb Saucer
 
 The **Crumb Saucer** is ShaiBot's Cookie-powered entertainment hub.
 
+#### Cookie Bakery
+
+Players can collect a fresh batch of Cookies from the Saucer.
+
+The Bakery and `/cookies collect` use the same shared collection
+utility, meaning they share:
+
+-   The same Mongo-backed cooldown
+-   The same reward range
+-   The same balance mutation
+-   The same profile/stat tracking
+
+The current default collection range is **1--1000 Cookies**.
+
 #### Slots
 
 -   Multiple Cookie wagers
 -   Embed-based reel presentation
--   Different symbol payouts and jackpots
+-   Different symbol payouts
--   Replay support
+-   Triplet combinations
+-   Jackpot support
+-   Run It Back support
 -   Shared Cookie vault
+-   Game-specific achievements and first-time global badges
+
+Slots triplets can participate in unique global badge progression,
+including Lemon, Cherry, Cookie, Star, and Diamond combinations.
 
 #### Blackjack
 
@@ -37,15 +126,33 @@ The **Crumb Saucer** is ShaiBot's Cookie-powered entertainment hub.
 -   Dealer stands on 17
 -   Natural Blackjack pays 3:2
 -   Push returns the wager
+-   All-In support
+-   Run It Back support
 -   Persistent active hands
 -   Per-player session ownership
 -   Safe simultaneous sessions
+-   Profile, achievement, and badge integration
+
+All-In state should be derived from the committed wager and the player's
+vault at the time the wager is made rather than solely from which button
+was pressed.
+
+Run It Back preserves immutable metadata from the previous hand. This
+allows historical challenges to remain valid even if another player
+changes the user's Cookie balance between rounds.
+
+For example, an All-In that pushes can be followed by Run It Back and
+still qualify for an All-In → Run It Back challenge even if Cookies were
+gifted to the player in between.
+
+Blackjack resolution is designed to guard against rapid repeated
+interactions so a hand cannot be resolved and paid multiple times.
 
 #### Roulette
 
 A compact European Roulette implementation using **0--36**.
 
-Available bets:
+Available bets include:
 
 -   🔴 Red
 -   ⚫ Black
@@ -57,12 +164,74 @@ Roulette uses repeated edits of the same embed for a
 rate-limit-conscious pseudo-animation. Zero loses on Red, Black, Odd,
 and Even.
 
+Roulette supports All-In and Run It Back tracking for profile
+achievements and special accomplishments.
+
 #### Vault Heist
 
 Players can attempt to steal directly from ShaiBot's Cookie vault using
 different risk/reward approaches such as **Sneak**, **Hack**, and
-**Smash**. Heist actions share a per-player cooldown so changing
+**Smash**.
-approach does not bypass it.
+
+Heist actions share a per-player cooldown so changing approach does not
+bypass it.
+
+Heist rewards and fines use percentage-based mechanics with hard caps so
+the system remains meaningful for wealthy players without allowing
+extreme balances to produce unreasonable penalties.
+
+### 🔁 Run It Back
+
+Supported Crumb Saucer games can track consecutive use of **Run It
+Back**.
+
+The streak represents the player's choice to immediately replay through
+the Run It Back action; wins, losses, pushes, jackpots, or other
+outcomes do not inherently break the streak.
+
+Current achievement concepts include using Run It Back five consecutive
+times in supported games:
+
+``` text
+One More Spin: Slots
+One More Bet: Roulette
+One More Hand: Blackjack
+```
+
+A normal/new wager breaks that game's Run It Back chain.
+
+### ♾️ I Can Do This All Day
+
+A special cross-game accomplishment tracks the sequence:
+
+``` text
+All-In
+→ round resolves
+→ Run It Back with the same committed wager
+```
+
+The original All-In is determined from immutable wager-time data. The
+Run It Back relationship is determined from the previous game's stored
+bet and All-In state rather than relying on the player's live vault
+remaining unchanged.
+
+This prevents another player gifting Cookies between rounds from
+invalidating a legitimate sequence.
+
+The accomplishment can exist both as a normal achievement available to
+everyone and as a global first-time badge for the first player to
+perform it.
+
+### 🏴 Cookie Stealing
+
+Normal player-to-player stealing is separate from Vault Heist.
+
+Steal difficulty can account for attacker and target wealth. Successful
+steals use randomized percentages with hard caps, while failed attempts
+can apply a percentage-based penalty.
+
+Profile tracking records relevant Cookie gains/losses and stealing
+activity.
 
 ### ⚔️ Crumble Strike
 
@@ -90,13 +259,6 @@ Roles are **DPS**, **Tank**, and **Healer**, with role-specific
 proficiencies. The general progression theme includes **Sprout →
 Adventurer → Warrior of Light**.
 
-### 🏴 Cookie Stealing
-
-Normal player-to-player stealing is separate from Vault Heist. Steal
-difficulty can account for attacker and target wealth, successful steals
-can use a randomized percentage with a cap, and failed attempts can
-apply a fee that feeds the bot vault.
-
 ### 📅 Raid Planner
 
 Raid planning uses Discord embeds and reactions. Participation can be
@@ -117,7 +279,8 @@ A typical layout:
 ShaiBot/
 ├── buttons/
 │   ├── crumbSaucer/
-│   └── crumbleStrike/
+│   ├── crumbleStrike/
+│   └── profile/
 ├── commands/
 │   └── applications/
 ├── events/
@@ -125,8 +288,12 @@ ShaiBot/
 ├── modals/
 ├── utils/
 │   ├── cookieEconomy.js
+│   ├── crumbCollect.js
+│   ├── crumbSlots.js
 │   ├── crumbBlackjack.js
 │   ├── crumbRoulette.js
+│   ├── cookieHeist.js
+│   ├── profileSystem.js
 │   └── crumbleStrike.js
 ├── index.js
 ├── package.json
@@ -144,6 +311,40 @@ client.selectMenus = new Collection();
 client.modals = new Collection();
 ```
 
+## Shared Utility Architecture
+
+Game/application files should remain thin wherever practical.
+
+Shared behavior belongs in `utils/`, particularly:
+
+-   `cookieEconomy.js` --- balances, transfers, cooldowns, and economy
+    primitives
+-   `crumbCollect.js` --- authoritative Cookie collection behavior
+-   `crumbSlots.js` --- Slots state and resolution
+-   `crumbBlackjack.js` --- Blackjack state and resolution
+-   `crumbRoulette.js` --- Roulette state and resolution
+-   `cookieHeist.js` --- Vault Heist behavior
+-   `profileSystem.js` --- profile statistics, achievements, badges,
+    rendering, and audit helpers
+
+Application commands and button handlers should call these utilities
+rather than independently reimplementing economy or progression logic.
+
+This is especially important for features reachable from multiple
+interfaces. For example:
+
+``` text
+/cookies collect
+        │
+        ▼
+  crumbCollect.js
+        ▲
+        │
+Crumb Saucer Bakery
+```
+
+Both interfaces therefore share one authoritative implementation.
+
 ## Requirements
 
 -   Node.js
@@ -152,15 +353,14 @@ client.modals = new Collection();
 -   A Discord bot application/token
 -   `dotenv`
 
-Use the Node.js version required by the dependencies in your
+Use the Node.js version required by the dependencies in `package.json`.
-`package.json`.
 
 ## Installation
 
 Clone the repository:
 
 ``` bash
-git clone https://github.com/YOUR_USERNAME/ShaiBot.git
+git clone https://git.desq-gaming.de/Shaiwase/ShaiBot.git
 cd ShaiBot
 ```
 
@@ -210,7 +410,11 @@ M_URI=mongodb://USER:PASSWORD@HOST:PORT/DATABASE?authSource=admin&retryWrites=fa
 
 Never commit database credentials.
 
-Important economy collections include:
+Important collections include Cookie balances, cooldowns, persistent
+game state, profile statistics, achievements, and global badge
+definitions/ownership.
+
+Core economy collections include:
 
 ``` text
 items_cookies
@@ -221,6 +425,10 @@ items_games
 `items_cookies` stores balances, `cooldown_cookies` stores action
 cooldown timestamps, and `items_games` can store persistent game state.
 
+Profile-related collection names should be treated as part of the
+profile utility's implementation contract rather than duplicated
+throughout command/button modules.
+
 ### Recommended Indexes
 
 Run the shared index initializer after MongoDB connects:
@@ -234,13 +442,15 @@ await mClient.connect();
 await ensureCookieIndexes();
 ```
 
-The intended unique keys are:
+The intended unique keys include:
 
 ``` text
 items_cookies      → userId
 cooldown_cookies   → userId + guildId
 ```
 
+Profile and badge utilities may establish their own required indexes.
+
 ## Discord Intents
 
 The current client uses intents including:
@@ -272,14 +482,20 @@ Enable any required privileged intents in the Discord Developer Portal.
 
 ShaiBot generally follows these conventions:
 
--   Public game output uses **embeds**.
+-   Normal user-facing messages, achievements, menus, and game output
--   Short private errors/feedback can use **ephemeral messages**.
+    are **public by default**.
+-   Errors, unauthorized interaction feedback, cooldown/debug-style
+    notices, and similar operational messages may be **ephemeral**.
 -   Games use **buttons** for interaction.
 -   Existing messages are edited where practical instead of repeatedly
     sending new messages.
 -   Game/session ownership is preserved so multiple users can play
     independently.
+-   Public menus may be visible to everyone without allowing other users
+    to control the owner's session.
 -   Animation-like effects use rate-limit-conscious message edits.
+-   Embed state should not be treated as the only authoritative source
+    for critical economy/game resolution data.
 
 ## Economy Safety
 
@@ -295,6 +511,14 @@ failures.
 When adding games, check that the house vault can cover the maximum
 possible payout before accepting a wager.
 
+Game resolution should be protected against rapid repeated interactions.
+A result must never be paid twice simply because two button interactions
+reached the server close together.
+
+Historical game facts such as wager amount, vault-at-wager, All-In
+state, and replay origin should be persisted when needed rather than
+reconstructed later from a player's live balance.
+
 ## Adding a Crumb Saucer Game
 
 Preferred pattern:
@@ -304,31 +528,80 @@ Preferred pattern:
     directory.
 3.  Reuse `cookieEconomy.js` rather than implementing separate balance
     logic.
-4.  Preserve the player/session owner through every screen.
+4.  Reuse `profileSystem.js` for statistics, achievements, and badges.
-5.  Check house liquidity before accepting a wager.
+5.  Preserve the player/session owner through every screen.
-6.  Prefer editing the current embed for animation/state transitions.
+6.  Check house liquidity before accepting a wager.
-7.  Protect wager resolution against rapid repeated interactions.
+7.  Prefer editing the current embed for animation/state transitions.
+8.  Protect wager resolution against rapid repeated interactions.
+9.  Persist immutable wager metadata required by achievements or replay
+    behavior.
+10. Keep application/button handlers thin and avoid duplicating shared
+    rules.
+
+## Achievement and Badge Design
+
+Achievements and global badges serve different purposes:
+
+**Achievements** are personal progression. Multiple players can earn the
+same achievement.
+
+**Global badges** are unique guild-wide distinctions and may have a
+single owner.
+
+When adding progression:
+
+-   Prefer stat-backed achievements for durable numeric milestones.
+-   Use explicit event tracking when the accomplishment depends on a
+    particular sequence or action.
+-   Keep generalized achievement naming consistent between games where
+    appropriate.
+-   Do not make collector completion depend on achievements that cannot
+    actually be obtained.
+-   Use atomic badge claiming so two players cannot both receive a
+    guild-first badge.
+-   Hidden/manual badges do not need gameplay evaluators if they are
+    intentionally awarded directly in MongoDB.
+
+## Administration and Auditing
+
+The profile system includes administrative/audit concepts for validating
+profile progression data and expected badge definitions.
+
+When changing achievement or badge schemas:
+
+-   Keep existing IDs stable once players may have unlocked them.
+-   Prefer adding new IDs over renaming historical IDs.
+-   Treat legacy/disabled definitions explicitly.
+-   Audit missing or malformed definitions after database changes.
+-   Avoid hardcoding optional manually managed badges as mandatory
+    configuration unless they are intended to exist in every guild.
 
 ## Roadmap / TODO
 
-The major planned Cookie systems are implemented or designed. Remaining
+ShaiBot is currently focused on testing, balancing, hardening, and
-work is primarily testing, balancing, and hardening.
+expanding progression.
 
--   [ ] Verify Slots replay behavior after deployment
+Near-term work includes:
--   [ ] Deploy and test limited Roulette
+
+-   [ ] Continue stress-testing simultaneous gambling interactions
+-   [ ] Continue testing repeated/double button presses
+-   [ ] Test insufficient-balance races
+-   [ ] Test behavior with a nearly empty house vault
+-   [ ] Validate All-In and Run It Back achievement edge cases
+-   [ ] Validate Run It Back streak progression across supported games
+-   [ ] Validate Slots triplet badge claiming
+-   [ ] Continue balancing Vault Heist rewards and fines
+-   [ ] Add Bankruptcy / starter recovery behavior
+-   [ ] Continue centralizing persistent interaction/session ownership
+-   [ ] Consider an economy audit/log collection
 -   [ ] Verify Crumble Strike AoE Revive behavior
 -   [ ] Verify Crumble Strike expiration/failure cleanup survives bot
     restarts
--   [ ] Balance boss HP, damage, healing, Energy, Limit generation,
+-   [ ] Balance Crumble Strike boss HP, damage, healing, Energy, Limit
-    entry costs, and rewards
+    generation, entry costs, and rewards
--   [ ] Stress-test simultaneous gambling interactions
--   [ ] Stress-test repeated/double button presses
--   [ ] Test insufficient-balance races
--   [ ] Test behavior with a nearly empty house vault
--   [ ] Consider dynamic Vault Heist payout caps
--   [ ] Consider an economy audit/log collection
 -   [ ] Add more Crumble Strike bosses, lore, and encounter variety
--   [ ] Add more Crumb Saucer attractions
+-   [ ] Add more achievements, hidden badges, and Crumb Saucer
+    attractions
 
 ## Security
 
@@ -343,6 +616,9 @@ node_modules/
 If a Discord token or MongoDB credential is accidentally committed,
 rotate it immediately.
 
+Do not expose administrative secrets or database credentials through
+embeds, logs intended for public channels, or repository commits.
+
 ## Disclaimer
 
 ShaiBot Cookies are fictional in-bot currency with no real-world
@@ -360,11 +636,15 @@ Bug reports, balance suggestions, and contributions are welcome.
 When contributing:
 
 -   Keep commands and button handlers modular.
--   Reuse shared economy utilities.
+-   Reuse shared economy and profile utilities.
 -   Avoid blocking the event loop.
 -   Be mindful of Discord API rate limits.
 -   Validate interaction ownership.
 -   Keep database operations safe under concurrent interactions.
+-   Preserve existing achievement/badge IDs where users may already own
+    them.
+-   Avoid introducing a second implementation of behavior that already
+    has a shared utility.
 
 ## License