Add agent badge inventory

[Vinaystwt]

Summary

• Add badge catalog metadata
• Add agent badge inventory endpoint
• Add global badge catalog endpoint with earned counts
• Add rarity filtering and validation
• Add focused tests and OpenAPI docs

What changed

• Added lib/gamification/badge-catalog.ts

• Added central badge metadata with:

  • badgeId
  • name
  • description
  • rarity
  • xpValue

• Added the five supported rarity tiers:

  • common
  • uncommon
  • rare
  • epic
  • legendary

• Updated reputation badge rarity typing to include uncommon

• Updated badge event typing to use the shared badge rarity type

• Updated renderer badge particle rarity typing to include uncommon

• Added GET /api/agents/[id]/badges

• Added GET /api/badges

• Updated OpenAPI docs

• Added focused route/catalog tests

Agent badge inventory

GET /api/agents/[id]/badges

Returns badges earned by the requested agent, sorted by earnedAt descending:

{
  "agentId": "bot-x",
  "badges": [
    {
      "badgeId": "rare-taskmaster",
      "name": "Rare Taskmaster",
      "description": "Completed 50 agent tasks in a single week.",
      "rarity": "rare",
      "earnedAt": "2026-06-01T00:00:00.000Z",
      "xpValue": 500
    }
  ],
  "total": 1
}

Behavior:

• Returns an empty list for registered agents with no badges
• Returns 404 for unknown agents
• Supports ?rarity=common|uncommon|rare|epic|legendary
• Invalid rarity returns 400

Badge catalog

GET /api/badges

Returns the badge catalog with earned counts:

[
  {
    "badgeId": "first-quest",
    "name": "First Quest Completed",
    "description": "Completed your first quest.",
    "rarity": "common",
    "xpValue": 50,
    "earnedByCount": 12
  }
]

Behavior:

• Supports ?rarity=common|uncommon|rare|epic|legendary
• Invalid rarity returns 400
• earnedByCount is calculated from reputation snapshots at query time
• Each agent is counted at most once per badge id

Tests run

• Focused badge route/catalog tests
• Existing reputation/badge-related tests
• npm test
• npx tsc --noEmit
• npm run build
• git diff --check

Verification

• Focused tests passed: 18/18
• Full suite passed: 403/403
• TypeScript passed
• Build passed with existing warnings
• git diff --check passed
• Generated .next, .data, root tsconfig.tsbuildinfo, and docs/superpowers artifacts are not included

Closes #334

[Vinaystwt]

Update: rebased onto latest upstream/main and fixed the upstream task-drain typecheck issue that appeared after the rebase.

Current status:

• CI / typecheck / tests / build: passing
• SonarCloud Code Analysis: passing
• Quality Gate: passed
• No conflicts with base branch

The remaining failing SonarCloud / SonarCloud Analysis check appears to be the external duplicate SonarCloud workflow/status issue, since the actual SonarCloud Code Analysis and Quality Gate have passed.

[leocagli]

Hi @Vinaystwt — this now conflicts with main after merging #375/#371 (openapi.json overlap). Please rebase and resolve; the badge logic itself looks good. 👍

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Vinaystwt]

Thanks — rebased onto latest main.

The stale task-drain follow-up commit has been dropped; the branch now contains only the badge inventory/catalog commit.

Verification:

• Focused badge tests passed: 18/18
• Full test suite passed: 483/483
• git diff --check passed

Note: local npx tsc --noEmit / npm run build currently fail on app/api/agents/[id]/capabilities/compat/route.ts due missing semver type declarations from the recently merged capability-versioning route. That file is outside this badge inventory diff.