step3/docs/QUESTION_COMPLETION_CREDITS.md

Question-completion credits

RZ Coin is awarded by the API for verified learning outcomes. The client displays award results but cannot choose award amounts or reason codes.

• A first correct answer earns 1 coin at difficulty 1-3, 2 at difficulty 4, and 3 at difficulty 5.
• A correct scheduled review earns 1 coin, or 3 when it recovers a miss after at least 24 hours.
• First-time system promotions to Practicing, Strong, and Mastered earn 3, 5, and 10 coins. Completing a real exam simulation earns 10 coins.
• Incorrect answers, skips, repeated submissions, and sample simulations earn nothing.
• Repeatable question and review rewards are capped at 30 coins in a rolling 24-hour window; milestone and simulation awards are outside that cap.
• Historical attempts are not backfilled.
• GET /api/credits returns the authenticated user's balance and current rolling-window capacity.
• The first-attempt response also includes the updated credit status.

The API is authoritative. Immutable attempt, review, simulation, and mastery identifiers make grants idempotent. Awards and purchases appear in the user's coin ledger. Credit accounts are included in account export and deletion.