Story 2548: Replace Credits with Billing & Usage

Why this exists. The old /settings/firm/billing page showed an AI-credit balance, a top-up checkout, and a per-lawyer credit-usage breakdown — vendor/token economics the firm was never supposed to see. Story-2545 shipped four firm-safe /app/billing/usage/* reads (current-period, receipts, breakdown, grants) plus the Story-2538 CREATE preflight. This story replaces the credits page IN PLACE with a Billing & Usage dashboard built on that contract: page pools (contracted/onboarding/offline-purchased), current-period usage with the READ(intake)/CREATE split, overage, allowance grants (including staff-recorded cheque purchases), and usage receipts. No tokens, AI credits, model costs, or vendor economics ever render here.

Same route, new page (AC1)

src/app/[locale]/(workspace)/settings/firm/billing/page.tsx is edited in place — no parallel route was created. The route still resolves BillingUsageRoute, RSC-prefetches current-period into a per-request QueryClient, and hydrates BillingUsagePage (src/components/settings/billing/billing-usage-page.tsx) so the primary pools/totals render on first paint (pramaan-docs ADR-095). The agent-surface key moved from settings.credits to settings.billing — a deliberate migration (the surface's job changed completely), not a rename of the old capability.

Individual / Firm + regional rate card (AC2)

UsagePoolsSummary reads currentPeriod.currency (INR/USD, the regional rate card identity) and derives an Individual/Firm badge from useAppGetSeatsAndBilling()'s seat count (active + invited <= 1 reads as Individual). The backend has no separate per-account-type GET; currency + seat count are the two real, live signals the customer-safe contract exposes.

Pools, usage split, overage (AC3)

PageUsageCurrentPeriodResponse is reconciled live from the immutable page ledger (Story-2545), never a cached projection. UsagePoolsSummary renders contracted / onboarding / offline-purchased pools each as granted-vs-remaining, then the intake/create used split, overage pages, and amount due — all in integer micros, formatted via formatMoneyMicros.

Cheque purchase as an immutable grant (AC4)

AllowanceGrantsList renders GET /app/billing/usage/grants (PageAllowanceGrantFirmView) — an offline purchase appears as grantType: "offline_purchase" with its receipt reference (externalReference) and validity window (validFrom/validUntil). The DTO itself omits grant_reason and the acting staff id (Story-2545), so internal notes never reach this view.

Preflight primitive (AC5, AC6 — partial, gap flagged honestly)

PagePreflightBanner (src/components/shared/page-preflight-banner.tsx) is a real, generic component wired to the live POST /app/billing/create-preflight mutation (useAppCreatePagePreflight) via the new BFF proxy. It takes a kind ("intake" | "create" | "generate-version") and renders the estimated-pages + max-charge copy, with the generate-version copy explicitly stating "Saving is free" before the billable-generation line (the free-edit-vs-billable-generate distinction AC6 asks for). Storybook covers all three kinds plus estimating/error states.

Completion evidence (AC7)

UsageReceiptsTable renders GET /app/billing/usage/receipts (PageUsageReceiptItem): actual pages, the allowance/overage split, amount, the document id as the version identity, and the receipt id. A credit receipt (failure/retry/blank-page) shows "No charge" instead of an amount — the reversal, not a fabricated charge.

Deletion census (AC9)

Backend /app/firm/credits* endpoints and their src/gen/ mirrors are untouched — Story-2545/PR#700 did not remove them, so deleting the generated client would just regenerate on the next pnpm codegen against the current mirror. Retiring those backend routes is a separate, out-of-scope follow-up.

Matter list/detail page volume (AC8 — NOT done, flagged)

Storybook coverage (AC10)

Codegen / OpenAPI mirror note

Story-2545's PR (pramaan-io/pramaan-functions#700) was still open (checks green, not yet merged) when this story started. The openapi mirror + permission-map diff from that PR were applied directly to openapi/app-api.json/openapi/permission-map.json in this worktree (git-apply of the exact committed diff) so pnpm codegen produced the real generated hooks/types/Zod schemas — not hand-authored contract mirrors (HR-22). If PR#700's content changes before merge, re-sync (git -C ../pramaan-functions pull origin main && pnpm codegen) and diff src/gen/ before merging this PR.

Verification

pnpm lint    # 0 errors, pre-existing warnings only
pnpm test    # 1330 passed; 1 file times out under full-suite parallel load
             # (clients-internal-route.test.ts), passes standalone/isolated —
             # pre-existing flake, unrelated to this change (no credits/billing
             # code in that file)
pnpm build   # NEXT_PUBLIC_ENV=local GATEWAY_SERVICE_KEY=dummy pnpm build — clean
pnpm check:routes    # 38 surfaces fresh
pnpm check:catalog   # 22 L1 surfaces, all carded or unsupported

i18n: every new string added to both messages/en.json and messages/hi.json under BillingUsage (+ SettingsNav.billingUsage, AgentSurfaces.settingsBilling); the old Credits namespace and its keys are removed. Token scan (rg '#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\(') is clean on every changed file — all colors are Badge/token-backed Tailwind utilities.