# ShaiBot Profiles, Achievements & Badges

ShaiBot's profile system is the permanent progression layer behind the
economy and games.

## Central Profile System

`utils/profileSystem.js` owns the main profile/progression behavior.

Important collections:

``` text
stats_profiles
items_achievements
guild_badges
config_achievements
```

Game modules should integrate with this system instead of creating
separate progression databases.

## Profiles

Profiles can track:

-   Overall game totals
-   Per-game statistics
-   Cookie gains and losses
-   Giving and stealing
-   Daily activity
-   Win/loss streaks
-   Weekday/time-of-day activity
-   Social relationships
-   Run It Back progression
-   Poker history
-   Achievement progress
-   Badge ownership

Profiles are intended to preserve meaningful long-term history.

## Profile Events

Prefer extending established event metadata rather than inventing
parallel event systems.

Common concepts include:

``` text
game_start
game_result
cookie_gain
cookies_given
steal_success
stolen_from_me
```

New wager metadata should prefer:

``` text
wager
```

Compatibility reads for older `bet`/`previousBet` fields may remain
intentionally.

## Activity

Profile activity uses a configured timezone.

Default:

``` text
Europe/Berlin
```

Activity supports daily streaks, weekly participation, weekday counts,
and broad time buckets.

Avoid making ordinary progression depend on excessively narrow
late-night windows.

## Social Progression

Profiles can store unique relationship sets for gifting and stealing.

Use set-style updates for unique users rather than appending duplicates.

Current social progression is intentionally scaled for a relatively
small community.

## Achievements

Achievements are personal: multiple players can earn the same
achievement.

Supported models include:

### Stat-backed

Best for durable lifetime milestones and reconciliation.

### Composite

Combines multiple durable conditions.

### Event-only

Used when the accomplishment depends on exact event context that cannot
reliably be reconstructed later.

### Hidden

Used for secret/special challenges.

Event-only achievements should not be treated as historically
backfillable when the necessary event was never stored.

## Achievement Notifications

Unlock notification is centralized.

Individual games should not create competing achievement announcement
systems.

## Global Badges

Global badges are guild-unique distinctions.

The common pattern is an atomic claim against an unowned badge:

``` text
guildId
badgeId
ownerId: null
```

then setting the winner.

This prevents simultaneous candidates from both owning the same
guild-first badge.

Achievements and badges are intentionally different:

``` text
Achievement → personal; many owners
Global badge → guild-unique; one owner
```

## ID Stability

Once achievement or badge IDs may exist in MongoDB, treat them as
persistent database identifiers.

Prefer retiring an old definition over renaming/deleting an ID that
players may already own.

## Reconciliation & Audit

Administrative tooling includes:

``` text
/profileadmin audit
/profileadmin reconcile dry-run:true
```

Reconciliation can backfill durable/stat-backed accomplishments.

Event-only achievements may be skipped because historical event context
cannot be invented safely.

When changing progression schemas:

-   use idempotent migrations
-   preserve existing values
-   preserve historical IDs
-   dry-run reconciliation first
-   do not fabricate data that was never tracked

## Poker History

Poker stores permanent statistics in the profile system rather than
retaining completed raw table documents.

Examples include:

-   hands played/won/lost
-   Cookies won/lost
-   largest pot
-   All-Ins
-   showdowns
-   action counts
-   streaks
-   hand-rank counters
-   pocket Aces wins
-   7-2 wins
-   fold wins
-   full-table wins

Poker profile tracking occurs after authoritative game state succeeds. A
profile failure must never corrupt a valid pot/economy settlement.