# Usage panel overhaul — owner brief

*A plain-language summary. The full build plan for the engineers is the sibling document.*

## What this feature does

Rebuilds the **Usage panel** — both the personal one (in Settings) and the org-wide one (in Admin) — so it finally reflects how we actually charge for AI: as a **budget you spend a percentage of**, not a token count. It strips out the old, confusing token numbers everywhere they still appear, shows exactly what's included (and what's unlimited) on your plan, and lets an admin **buy more right from the panel** — extra AI credits, more seats, or turning on overage — without bouncing over to the billing page. It also gives the same clean view to your internal operator console for any tenant.

## Architecture decisions

- **One source of truth.** The panel reads the real, enforced plan limits from the database — the same numbers the marketing pricing page already shows (those two are in sync today, and we add a small automatic test so they can never quietly drift apart again).
- **AI is money, not tokens.** Everything AI-related is expressed as "you've used X% of your plan's AI budget this cycle," with a reset date. The token counts that used to show up in four different places are removed from view. More importantly, we turn off the old hidden token limit that could silently block someone's AI with a message an admin couldn't even see anymore — including a second place that was blocking AI *agents*.
- **Reuse, don't rebuild.** We extend the components and screens that already exist rather than inventing parallel ones; the one genuinely new build is the operator-console usage view (which, it turns out, never existed at all).

## Logic decisions

- **Add-ons are wired in for the first time.** Buying extra seats from inside the app has actually never had a button anywhere — this is its first real wiring, so it gets a careful test against the payment flow.
- **History gets AI spend.** We start recording AI spend per cycle so the usage history can show it over time (the table literally had nowhere to store this before).
- **Permissions get tidied.** A few inconsistencies are fixed: who can see dollar figures is now tied to a real permission instead of a hardcoded role; a team manager now sees only *their* team's usage instead of everyone's; and the same permission governs every allocation control (today they disagree).

## UI decisions

- **Calm, not cluttered.** One AI budget meter as the hero, a quiet "where it's going" list (no more six-color rainbow bar), and grouped rows for everything else — each either a single clean bar or a calm "Unlimited" label. It follows the same refined, near-monochrome style as the redesigned homepage.
- **Unlimited is shown on purpose.** Most competitors hide unlimited items; we show them as a reassuring label so you can see how much your plan includes.
- **The admin screen stops hiding things behind tabs.** It becomes one continuous scroll, and it finally gets the org-wide AI budget meter it never had.

## What this touches

Personal usage screen · org/admin usage screen · the operator console's per-tenant view · the AI budget + credits + seats + overage plumbing · usage history · usage threshold alerts · the help-center articles · and a handful of permission and correctness fixes. Everything extends what's already there; nothing is a throwaway parallel system.

## Decisions needed from you

You already settled the four big ones (full token cleanup, all add-ons inline, AI spend in history, rebuild both the admin and operator views). Two small, deferrable calls remain — I've picked sensible defaults and noted them for the edge-case pass, so they don't block anything:

1. **The "you're on pace to finish your budget by the 24th" projection line** — a nice differentiator no competitor has. Default: build it if it's cheap, otherwise ship without it in v1.
2. **Exactly how overage looks once you pass 100%** — default is "100% of plan budget, plus $Y in credits used" rather than a meter that goes past full.

→ Full implementation plan: the sibling document for the engineers.