docs(payments): require admin-page sync on money-model changes

[fbac]

Summary

• Adds a rule to the money law (src/payments/AGENTS.md): any change to how credits are stored, computed, or displayed (new GrantKind/LedgerReason, changed getBalance/spendable meaning, changed entitlement math) MUST carry a matching update to the credits admin page.
• The admin page hard-codes the balance model and is not generated — the Option-B → single-ledger migration changed what balance means but skipped it, leaving two balance cards rendering identical numbers under stale labels. This rule is the meta-fix for that drift.
• Wired into both the add-a-money-flow checklist and a dedicated section.

Test Plan

• prettier --check clean (docs-only)

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

Note

Document requirement to sync credits admin page on money-model changes

Adds a checklist item and dedicated section to AGENTS.md instructing engineers to update src/api/v2/credits-admin/ whenever the balance model, GrantKind/LedgerReason set, or entitlement math changes. The admin page is hard-coded (not generated) and must be kept in sync manually, covering the ledger view, balance cards, and subscription entitlement figures.

^{Macroscope summarized 412b8ec.}

[coderabbitai]

Warning

Review limit reached

@fbac, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 59 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2ab80651-a2d2-4f9f-b20a-3155e482a75d

📥 Commits

Reviewing files that changed from the base of the PR and between 7b11e05 and 412b8ec.

📒 Files selected for processing (1)

• src/payments/AGENTS.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fbac/agents-md-admin-page-sync-rule

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Claude finished @fbac's task —— View job

---

PR Review Complete ✅

Todo List

• Read the modified src/payments/AGENTS.md file
• Review documentation changes for clarity and completeness
• Provide constructive feedback

---

Review Feedback

This is an excellent documentation addition that addresses a real operational problem. The changes are clear, well-motivated, and appropriately positioned.

Strengths ✅

1. Clear motivation: The PR description and inline example (Option-B migration leaving stale admin page labels) make the why immediately clear.

2. Perfect placement: Adding this as step 6 in the "Adding a new money flow" checklist is exactly right — it's where developers will naturally encounter it when implementing changes.

3. Comprehensive coverage: The new section covers all three failure modes:

   • New GrantKind/LedgerReason not surfaced in ledger view
   • Changed balance semantics not reflected in UI labels
   • Changed entitlement math not updating subscription displays

4. Actionable guidance: Each bullet specifies what triggers the requirement and what needs to be updated (e.g., "New GrantKind / LedgerReason → surface it in the ledger view").

5. Strong framing: "Treat the admin page as part of the blast radius" establishes the right mental model — this isn't optional polish, it's part of the change's correctness.

6. Writing quality: Consistent with the rest of the doc's direct, technical tone. No fluff.

Minor Suggestions (Optional)

1. Consider adding a specific file path in the checklist step 6:

   -   page too — see the next section.
   +   page too (src/api/v2/credits-admin/) — see the next section.

   This helps developers immediately identify which code they need to touch.

2. Potential future enhancement (not blocking): If src/api/v2/credits-admin/ grows more complex, you might eventually add a comment in that directory's main file pointing back to this AGENTS.md section. But that's overkill for now.

Code Quality Assessment

• ✅ Accuracy: All technical claims are correct (verified against the codebase)
• ✅ Completeness: Covers the identified gap without scope creep
• ✅ Maintainability: Future developers will find this when they need it
• ✅ Consistency: Matches existing doc structure and voice
• ✅ Test coverage: Appropriate for docs-only change (prettier check)

Security & Performance

• N/A (documentation change only)

Verdict

Approve and merge. This is exactly the kind of meta-fix that prevents future production issues. The rule is clear, actionable, and well-integrated into the existing checklist workflow.

---

Branch: fbac/agents-md-admin-page-sync-rule

[macroscopeapp]

Approvability

Verdict: Needs human review

Documentation-only change adding guidance to AGENTS.md in the payments directory. The file is owned by xmtplabs/engineering, and designated code owners should review changes to their documentation even when trivial.

^{You can customize Macroscope's approvability policy. Learn more.}