Usage dashboard — the money, by step

A rebuild of the console's Usage & cost tab into a real dashboard: daily / weekly / monthly views, cost per function in the final vocabulary (speech · fp · tool.* · kit.* · photo.* · persona.* · room.* · app.*), cost by model tier, daily token volume, and a double-click drill-down for any period.

1 · The dashboard

Three design notes on what you just used:

• The stack is the seven prefixes, and the eighth colour is held in reserve. Every stored kind is group.leaf; the chart colours the group, the drawer lists every leaf. The spare colour is the trial slot — a mechanism for promoting one leaf to its own segment while it is being judged, then folding it back with a one-line commit (USAGE_TRIAL). persona.growth held it for the day the dashboard shipped and was folded back the same day, which is the point: a permanent trial slot is just an eighth group wearing a badge. Empty is the resting state. Eight is the ceiling a stacked bar stays readable at (and the ceiling the palette is validated at), so there is no "Other" — only the gray pre-ledger era.
• The gray left edge of Weekly / Monthly is honest history. Before the new ledger ships there is no per-function record (§2), so old days can only ever show an unsplit gray bar. The mock renders that era so you can see what the real tab will look like on day one, not after a year.
• The Tokens lens stacks by token class, not by function — cache read vs new input vs cache write vs output. "We use more and more tokens" is a cache question before it is a function question: cache reads are ~10–30× cheaper than fresh input, so the same token count can be wildly different money. One blue ramp, palest = cheapest.
• The $ by model lens (owner, 2026-09-10) is the same money split by WHO ANSWERED rather than by what asked — the chart and the By model tier bar under it become two views of one number, so a jump in the column has a name the moment you see it. The buckets carry their own per-model split (periods[].models, folded on canon_model so an alias is one model — _merge_models' rule applied per bucket); the bucket's totals are untouched, this reads the same rows a second way. Colour is the window's own cost rank, which is how that table already colours its rows, so a model wears one hue down the whole page. ⚠ The slots ARE the palette, and the palette holds eight. The table can give every model past the eighth one shared hue because each of its rows carries a name; a stacked column cannot — two segments of one colour meaning two things is the one thing a chart may not do. So eight slots are eight models, and only when there are more models than slots does the last slot become other models. That is the same reason there is no "Other" in the function lens above: eight is the ceiling, and what exceeds it has to be named honestly, not colour-collided.

2 · The ledger (why it needed one new table)

Before this build the per-function split never reached the database. Room._tally() already sees every provider call with its kind — but only accumulates it in memory, per room, all-time. The DB ledger turn_events books one row per whole turn (speech + FP + prop + act + dispatch summed), with no kind and no cache-token columns. And two functions bill nowhere at all today: the dreamer and the growth sweep only print their cost to stderr.

Volume: a busy day is a few thousand calls — SQLite yawns. A year is ~1M rows; if it ever matters, a monthly rollup table is a follow-up, not a prerequisite. The dashboard's aggregates are three GROUP BY substr(ts,1,10) queries.

3 · The vocabulary (final, 2026-08-21)

Every stored kind is group.leaf — lowercase, dot between group and leaf, stable forever (it is a row in the ledger). The group is the stack slot; display labels are a separate map and may change any day. "merged" = the split exists in memory today but lands in the turn row unsplit; those all start writing call_events rows through _tally on day one.

In the By function table the shape carries this on its own: a group holding several leaves names the group and lists them indented beneath it; a group holding one is named by that leaf alone, with nothing indented under it. The table used to say so in a caption under its header — the captions came off the cost page (owner, 2026-08-24), so the rule is written here instead.

A leaf may belong to a FAMILY (2026-09-09, the owner:「app.ink is still a major function under App, and when we click on app.ink, it expands to app.ink_desk, etc」). The rule is the underscore, and it is the one the vocabulary already used: app.ink_writer belongs to the family named by the part before it, app.ink. A family stands where a leaf stands — summed, badged with its seat count, and shut — and opens one indent deeper on a click. Every other kind is a family of one and is drawn as the plain leaf it always was, so nothing outside Ink moves. The bare app.ink — rows booked before the 09-02 split — falls into the Ink family by the same rule and is one of its leaves. It is the same shape Models & APIs took the same day: there Ink is one card headed app.ink, with a plain sub-head per seat; here the seats are where the money is, so here they open.

Not in the table because the app never pays for it: read-aloud TTS is the browser calling OpenRouter on the user's own key.

The Ink leaves book one row per provider call (09-04, the owner:「why only 1 call for the writer?」). The brew holds its usage in memory and writes it at the end of a pass; until this fix it summed the pass per (leaf, model) into a single row, so a whole night's writing read in the console as one call. Every booking now appends the call itself and the drain writes a row each — the rule the rest of the table already keeps.

4 · What shipped

1. The ledger. db.call_events + one write at the _tally seam (best-effort — the books never break a turn) + record_turn(kind=…), an opt-in that lets the five function pseudo-rooms book both books at once. turn_events untouched.
2. Three spends that had no bill at all now have one: persona.dream and persona.growth (stderr-only until today), and persona.embed — the embedder, which returns no usage object and had no price row, so the card ranking at room open, the memory router and the dream all spent real money that nothing in the app could see. It is priced input-only with a chars/4 token proxy, and metered at one seam (wordpick._post_embed) so a fifth caller cannot forget it.
3. The rename. Every call site carries the §3 vocabulary; KIND_ALIAS renames a retired kind at read time, so nothing on disk is rewritten and last week's room reads correctly in today's panel. ⚠ At the ship this covered a room's by_kind only — see「the alias has to run where the reading happens」below.
4. The caps got complete. take_turn_spend() drains what _tally actually saw, so a turn is billed for every call it made. It used to carry speech + fp + dispatch only — tool, game, translate and memory calls were capped by nothing and appeared in no total. The old three-field sum survives as a floor, so no path can bill less than it did before.
5. The endpoint. GET /api/admin/usage2?start=&end=&tz=±N — ONE scope, ONE answer: the chart's buckets plus all four standing analyses, every one filtered by the same window. start/end are the LOCAL calendar dates the reader picked, because a date typed into a calendar means the date on that calendar.
6. The tab. Console ▸ Usage & cost — the time scoper (Today · Yesterday · Last 7 · Last 30 · This month · Last month · Custom, with a two-month range calendar), the chart, and the four analyses. The all-time By-user card and the Studio backfill stay below it: they are deliberately unscoped.
7. The gate. Twelve ledger checks in lib/smoketest.py, incl. the double-count guard (a function books both books; a chat turn books only the ledger) and the timezone one.

Since the ship — one model, one row

A room books its turns under the picker's model id and the eyes book theirs under the API's, and for the vision model those differ（deepseek-v4-flash-vision vs -exp）— so the by-model tier and the chat's cost panel showed the same model twice, one of them raw. cost.MODEL_ALIAS + canon_model now write the canonical id at the tally seam and at book_call, and every by-model read merges already-written rows through the same alias. ⚠ The ledger is never rewritten — the fold happens on the way in and on the way out, so a row booked last week still reads correctly today.

Since the ship — the alias has to run where the reading happens

Re-grouping game.*→kit.* and lifting photo work into its own photo.* group changed nothing at all on either surface, and both went on showing room.photo under a room group. KIND_ALIAS was applied at book_call (write) and when a room loads its state.json — but never when reading call_events, where GROUP BY kind returns the raw stored string. New rows carried the new name because the call site passed it; the ~70 rows already booked kept theirs forever.

The vocabulary now lives in db.py, beside the table whose kind column it describes — the reader needs it and db must not import run_room, which re-exports it. usage_window() and room_cost() fold every row through kind_now on the way out (_fold_kinds), and two eras of one kind merge onto one row rather than sitting beside each other — the by-function table, the chat panel and the chart's stack all at once. ⚠ An alias that only runs on the write path renames nothing; it is the read that has to fold, and a silent no-op looks exactly like a working rename.

5 · Still open

• Retention — call_events is kept forever (~1M rows/yr, which SQLite does not notice). A monthly rollup is a follow-up if it ever matters, not a prerequisite.
• The trial slot is empty — USAGE_TRIAL = (). Growth folded back into persona on ship day; the mechanism stays for the next thing worth watching, and empty is its resting state.
• Per-function caps — "Vibes may spend ≤ $0.50/day" is now a one-query feature. Out of scope until asked for.
• The bench is not in here. exam/* runs from the dev PC against the APIs directly and never reaches the box's ledger — that is dev cost, and its own page.