docs(agents): record why app metrics prints raw tokens where the web humanises them

[ZacxDev]

civitai/civitai#3574 humanises the two analytics "top N" rollups on the web (analytics-bucket-labels.ts), so the same data now reads as Generations / AI workflow submits there and workflow:submit / ai:write:budgeted in civitai app metrics.

This records that as a deliberate non-mirror (AGENTS.md item 8) rather than leaving the next reader to find the divergence and "fix" it.

The reasoning, written down so it can be re-litigated on evidence

Mirroring the labels would add a third vendored mapping to keep in lockstep with the server — alongside schema/ and the slot registry — and unlike those two it buys no correctness. A raw token is accurate, just terse, and #3561 already bounded the values so they aggregate readably. Raw is also arguably the better choice for the CLI's scripting audience, and --json must keep emitting raw tokens regardless.

The costs, since a deliberate decision should carry them

• An author reading the same range on both surfaces sees two vocabularies.
• A legacy pre-bounding row reads workflow:submit:<id> here vs Generations (<id>) on the web.
• And the trap for whoever does close the gap: pending in a legacy endpoint tail is a "no id captured" sentinel, not a status — that was a real bug #3574 shipped and then fixed, and hand-rolling labels here would reproduce it.

If the gap is closed later, the note says to mirror analytics-bucket-labels.ts wholesale and add a drift check against the server's recordScopeInvocation call sites, rather than hand-rolling.

Verification

Confirmed against the code before writing the claim: internal/cmd/app_metrics.go:255,263 print safeTerm(s.Scope) and safeTerm(e.Endpoint) under the Top scopes / Top endpoints headings — i.e. raw. Docs-only change; make ci green.

🤖 Generated with Claude Code