docs(backend): GAMIFICATION.md documents an XP reward table that does not exist in the code

[diegosouzapw]

Split out of #12426, which surfaced this while auditing the XP award path. Found by @pacocartones — thank you.

docs/frameworks/GAMIFICATION.md:239-252 documents an XP reward table that does not match XP_REWARDS in src/lib/gamification/xp.ts:155-160. The docs are not describing a version of the code that exists.

Names that exist only in the docs

Documented	Value	In XP_REWARDS?
badge_earned	25	❌ — the code has badge_unlock: 10
streak_milestone	15	❌ — the code has streak_bonus: 2
referral	—	❌ no such action
model_diversity	—	❌ no such action
compression_use	—	❌ no such action
skill_use	—	❌ no such action

Values that disagree

Action	Docs	Code
token_share	5	1
daily_login	3	5

Decision needed before fixing

Which table is authoritative? Correcting the docs to match the code and raising the code's rewards to match the docs are both defensible, and the answer determines whether this is a docs-only change or lands together with #12426 (which tracks the fact that streak_bonus and badge_unlock are never paid at all — getXpForAction in src/lib/gamification/events.ts:108-120 uses its own hardcoded table that stops at daily_login).

Per AGENTS.md → "Documentation accuracy", documentation must describe verified behavior. Right now this table would fail that gate.

Refs #12426

[KooshaPari]

Docs already match code on main

Just checked both files at main:

src/lib/gamification/xp.ts — 10 XP_REWARDS keys:

export const XP_REWARDS: Record<XpAction, number> = {
  request: 1,
  provider_switch: 5,
  model_switch: 3,
  combo_create: 10,
  combo_use: 2,
  token_share: 1,
  invite_redeem: 50,
  daily_login: 5,
  streak_bonus: 2,
  badge_unlock: 10,
};

docs/frameworks/GAMIFICATION.md — XP Rewards table contains exactly these 10 entries (request, provider_switch, model_switch, combo_create, combo_use, token_share, invite_redeem, daily_login, streak_bonus, badge_unlock) with matching values and descriptions.

The other 6 entries I saw mentioned in the issue (badge_earned, streak_milestone, referral, model_diversity, compression_use, skill_use) don't appear in either the code or the docs on main — they may have been from an older revision or a different branch.

I'd argue code is the source of truth (it's what actually awards XP), so docs being aligned with code is the correct state. Closing this as resolved unless you want me to open a PR that pins the contract with an integration test (expect(Object.keys(XP_REWARDS).sort()).toEqual(parseDocsTable().sort())) so a future drift can't sneak through.

[KooshaPari]

Update: scratch the previous comment. I checked again with a fresh checkout and the docs DO have 12 entries (3 phantom + 3 missing + 2 wrong XP values). Real PR opened: #12667