Learn TokenOne^® end to end.

Every AI call coming through TokenOne gets read, planned, delivered, verified, optionally escalated, and fed back. The wallet debits in real time, the ledger seals the entry, and the savings against your chosen benchmark provider are computed on every row.

You configure TokenOne once (wallet top-up, benchmark provider, project budgets, integration tier), then your team keeps working in the tools they already use. TokenOne handles the policy, the redundancy and the accounting.

1. How much have I spent and how much have I saved? — see /overview + section 8.
2. Which calls did TokenOne actually make on my behalf, and why? — see /analytics + /settings/ledger.
3. How do I plug TokenOne into the tool my team is already in? — see section 5 — connectors.

These five phrases appear on every customer-facing surface. The wording is intentionally fixed so the savings story stays consistent across screens.

Tokens saved

absolute count

Tokens TokenOne governed delivery preserved vs the benchmark provider.

% saved

ratio

Tokens saved as a share of benchmark-equivalent burn.

Benchmark provider

brand

The provider you selected as the comparison anchor (OpenAI, Anthropic, Google, xAI, Meta).

TokenOne burn

tokens

Real tokens consumed via TokenOne governed delivery. (Replaces "Actual burn", retired 2026-05-27.)

<Provider>-equivalent burn

tokens

What the same workload would have cost at the benchmark provider's pricing. Renders as "Anthropic-equivalent burn", "OpenAI-equivalent burn", etc.; falls back to "Benchmark-equivalent burn" when no provider is selected. (Replaces "Baseline-equivalent burn", retired 2026-05-27.)

One balance per tenant. Tops up via Stripe (test mode in dev). Every AI call debits BigInt-precise token counts; the ledger seals each debit and the wallet balance is the running source of truth.

balance

BigInt

Spendable tokens, integer (BigInt because token counts cross JavaScript's safe-integer ceiling fast).

reserved

BigInt

Tokens earmarked for in-flight calls. Released on completion or failure.

debited

BigInt

Tokens already spent in this window (24h / 7d / 30d depending on screen).

runway

days

balance ÷ rolling daily burn. Shown on /overview as "X days at current pace."

auto-topup

rule

Optional. When balance < threshold, charge the saved card for the configured amount.

Top-up flow: /billing → Add tokens → Stripe checkout → webhook → wallet credit → ledger entry. The ledger entry is the audit row; the wallet row is the running balance.

Three layers run on every call. Layer 1 picks the model class (deterministic, <5ms p99). Layer 2 picks the compute endpoint (provider health, region, residency, failover). Layer 3 is the QA feedback loop, scoring responses and feeding suppression / escalation rules back into layers 1+2.

task family

classification

coding / writing / research / data-analysis / etc. Drives which model class wins.

complexity

low | medium | high

Heuristic on prompt + context. Higher complexity climbs the quality ladder.

quality floor

rubric score

The minimum acceptable QA score. Below this, the call escalates.

approved delivery path

path

The model + compute endpoint actually used. Logged on every llm_call_logs row.

escalation

event

When QA fails, TokenOne retries up the ladder. The user receives the better answer; the failed attempt is in the ledger.

The six ways TokenOne plugs into AI workflows. All six route through SmartOne; the difference is only the shape of the integration. Full table in section 5.

1. Proxy — drop-in OpenAI / Anthropic / Google-compatible endpoints. One env var change.
2. MCP server — Claude Desktop and any MCP-aware client.
3. Browser extension — for clients that can't be proxied.
4. Desktop bridge — local app on the user's machine.
5. Copy-paste — manual fallback.
6. Advisory — read-only "what would TokenOne do" mode.

Every wallet event becomes a ledger entry. Entries are HMAC-SHA256 chained: each row's seal hash includes the previous row's. The chain is verifiable end-to-end with GET /api/tenant/ledger/verify. Customer-facing event types are mapped to plain-English labels ("Top-up", "AI usage", "Refund", etc.) — internal type codes stay in the admin view.

seal hash

hex

HMAC-SHA256(prev_hash + entry_payload, LEDGER_HMAC_KEY).

prev hash

hex

The previous entry's seal hash. The chain unravels if any row is altered.

event type

enum

Internal: WALLET_TOPUP, AI_USAGE, REFUND, ADJUSTMENT. Customer view: plain labels.

amount micros

BigInt

Tokens debited or credited, signed.

project id

UUID

Which project the entry attributes to. Lets /analytics group spend per project.

A read-replica analysis loop scores every response asynchronously. Scores feed back into routing (suppression / escalation), into the benchmark math (was the delivered answer actually as good as the baseline-equivalent would have been), and — when promoted — into the offline learning plane.

accuracy

0..1

How factually correct the response is against the prompt's intent.

structure

0..1

Did the response respect the requested format (JSON, markdown, etc.)?

hallucination risk

0..1

Higher = more likely to fabricate. Triggers escalation above threshold.

instruction fidelity

0..1

Did the model follow the system prompt + user instructions?

The first screen after login. Five hero tiles + a savings chart + a live activity feed. Designed so an executive can read the project's health in under 10 seconds.

Wallet balance

Current balance in tokens + USD-equivalent. Click → /billing.

Tokens saved (30d)

Absolute tokens preserved vs the benchmark provider in the last 30 days.

% saved (30d)

Same number as a share of benchmark-equivalent burn. The headline KPI.

TokenOne burn · 30d

Real tokens consumed via TokenOne governed delivery in the last 30 days.

Runway

Days remaining at current rolling burn rate.

Savings chart

Daily line: TokenOne burn vs <Provider>-equivalent burn over the window. Toggleable 7d / 30d / 90d.

Live activity feed

Last 50 events: AI usage, top-ups, escalations, threshold alerts. Click any row → /analytics filtered to that ID.

Drill-downs grouped into Usage / Savings / Ledger / Audit. Each tab queries the insights-engine — the read-only aggregator that powers every chart and table on customer-facing surfaces.

Usage tab

Token in/out per task family, per project, per hour. Compare two date ranges.

Savings tab

Per-day actual vs baseline-equivalent. Hover any point → drill to the calls in that bucket.

Ledger tab

Filterable list of every ledger entry. Running balance column on the right.

Audit tab

Decision summaries: why TokenOne picked the path it did on each call, evidence trail, change log, export log.

Search filter

Free-text filter on activity rows — matches against prompt fragments, project name, model id.

Engine versions

Each chart footer lists the insights-engine version that produced it. Versions bump on every locked-wording change.

A printable, screenshot-friendly recap. Auto-emailed to the wallet owner on the configured cadence. Same KPIs as /overview but with period-over-period deltas and one sentence of human-readable commentary per row.

Period selector

Today / Yesterday / WTD / MTD / Custom. Defaults to the cadence set in /notifications.

Delta

Numeric change vs previous comparable period. Green if direction is positive for the metric, red otherwise.

Top movers

The three metrics with the largest absolute movement in the window.

Personal settings, not tenant settings. Powered by the users table (the columns shipped 2026-05-26: timezone, bio, avatar_url, email_verified_at).

Name

Display name. Surfaced on email + activity feed.

Email

Login + recovery email. Verifying it sets email_verified_at.

Timezone

Used for /summary delivery time + activity-feed timestamps.

Bio

Optional free text. Visible to other tenant users in /security → team.

Avatar URL

Optional. Rendered in the header chip.

Where you fund the wallet and choose the benchmark provider. Stripe lives here.

Add tokens

Stripe checkout. Increments balance and writes a WALLET_TOPUP ledger entry.

Auto-topup

Threshold + amount. Fires the same Stripe flow programmatically.

Benchmark provider picker

OpenAI / Anthropic / Google / xAI / Meta. Sets tenants.baseline_provider_key; every new call gets a baseline-equivalent comparator computed against this brand's pricing.

Payment method

Card on file. Saved via Stripe; TokenOne never sees raw card data.

Invoices

Historical receipts. PDF download per top-up.

Active sessions + API tokens + audit trail. The Active Sessions tab is where the idle-logout auto-sign-out dropdown lives (writes tokenone-session-idle-msto localStorage; the SessionManager reads it every 30s).

Active sessions

All devices + locations holding a valid refresh token. Revoke any with one click.

Auto sign-out

Idle threshold dropdown (15min / 1h / 4h / 24h / never). Changing it rewrites the localStorage key.

API tokens

Personal access tokens for CLI / scripts. Scoped per tenant.

Audit log

Login / logout / token-revoke events. Tamper-evident.

Two types of alerts: balance / runway thresholds and quality / escalation events. Configurable per channel (email / webhook).

Balance threshold

Trigger when wallet balance drops below N tokens.

Runway threshold

Trigger when runway drops below N days.

Escalation alert

Trigger when an in-flight call escalated above the quality floor.

Digest cadence

Daily / weekly. Drives /summary email delivery.

Webhook URL

Optional outbound URL for any of the above alerts. Signed payloads.

The connector catalogue. Each tile is a tool (Claude Desktop, Cursor, VS Code, ChatGPT-compatible client, etc.) with a tier-specific setup wizard.

Tile

Tool name + tier + status (connected / disconnected / not configured).

Setup wizard

3-5 step flow per tile. Generates API keys, copies config snippets, validates the round trip.

Connection test

Sends a dummy prompt through the integration end-to-end. Surfaces failure mode if it doesn't round-trip.

Tier badge

Proxy / MCP / Browser / Desktop / Copy-paste / Advisory.

The technical operator surface. Three sub-pages: Clients, Tools, Model Marketplace.

/developer-zone/clients

API keys per environment (dev / staging / production). Format: tp_dev_xxx / tp_live_xxx. Rotation with 24h overlap window.

/developer-zone/tools

Internal tool catalogue: shell, browser, etc., available to your project's AI agents.

/developer-zone/model-marketplace

Read-only catalogue of every model SmartOne can route to, with capability tags + per-token pricing per brand.

One workspace per project. Each workspace owns its own budget, its own quality floor, its own integrations list and its own activity stream — but inherits the tenant wallet.

Workspace switcher

Top-bar dropdown. Switching changes the project context for the entire app.

Project settings

Per-project budget + quality floor + benchmark override (rare; defaults to tenant).

Activity

Filter the global feed to this project only.

The complete ledger as a paginated table. Filterable by event type, date range, project, amount. Includes the verify button that calls GET /api/tenant/ledger/verify and reports any chain breaks.

Event type

Customer label (Top-up / AI usage / Refund / Adjustment). Hover to see internal type code.

Amount

Tokens debited or credited. Signed integer, BigInt-precise.

Running balance

Cumulative wallet balance as-of this row. Computed server-side; seeded from the first row.

Seal hash

First 8 chars of the row's HMAC seal. Full hash visible on row expand.

Verify chain button

Walks every row in the window, recomputes each seal, returns the first broken row id (or null).

The live plane (every customer call) emits an outbox event per dispatch. The learning plane consumes the outbox asynchronously and walks it through six stages: outbox → evidence → pattern → signal → proposal → validation. Only the validation stage writes to anything customer-visible — and even that stays in admin until governance approves a promotion.

Phase 1 is the ingestion + signal-detection chain. Slice 1 ends at proposal[minted]. Every row is append-only; the plane reconstructs state from history, not from in-place edits.

LearningOutboxEvent

table

One row per dispatch. Fields: tenant, project, request, response, model id, token counts, quality score, latency, timestamp. The raw stream.

LearningEvidence

table

Aggregated, de-duplicated outbox events. Same shape but grouped by content hash so the same request pattern doesn't flood downstream stages.

LearningPattern

table

Rolled-up evidence by classifier features (task family, complexity, response shape). Patterns are what signals fire against.

LiveCoverageSnapshot

table

Per-tag coverage view: which task families have enough evidence for which signals to be statistically valid.

Live*Signal (6 tables)

tables

Six signal detectors (cost, quality, latency, drift, coverage, escalation) each write rows when they fire. A signal that fires N times in a window mints a proposal.

LearningProposal

table

The candidate-rule row. status starts at minted in Phase 1 and STAYS there through all of Phase 2.

Phase 2 takes a minted proposal and proves whether it should ever be promoted — without mutating runtime. Six stages: synthetic generation → quality scoring → replay → Gate 1 (synthetic) → Gate 2 (replay) → cost attribution.

LearningSyntheticGenerationPolicy

table

The policy a synthetic batch is generated under. Tier A/B/C, max cases per batch, max cost, min quality threshold, generator template, optional model id.

LearningSyntheticBatch

table

One batch per (proposal, policy, evidence window). Status: generating → scored | rejected. Records actual cost.

LearningSyntheticCase

table

One row per generated case. Carries inputBlob, optional expectedBlob, tags, deterministic caseHash, and generationMethod (template / cheap_model / frontier / fixture).

LearningSyntheticQualityScore

table

1:1 with cases. Four dimensions: duplicationScore, noveltyScore, discriminativePower, coverageContribution. Plus accepted bool + rejectionReason.

LearningReplayRun

table

One run per (proposal, batch). Replays the accepted cases through the proposal's would-be rule and records pass/fail counts.

LearningReplayResult

table

One row per replayed case. Carries actualOutput, expectedOutput, passed bool, divergenceReason.

LearningProposalGateResult

table

Append-only gate evaluation history. gate_id is 'synthetic' (Gate 1) or 'replay' (Gate 2). Each evaluation writes a NEW row; the proposal's denorm pointer points to the latest.

LearningProposalValidationCost

table

Per-proposal cost tally. Refreshed from source on every Phase 2 step. Denormalised to proposal.validationCostMicros.

LearningPlaneBudgetWithdrawal

table

Append-only audit row per $-spending operation. Idempotency key prevents double debits.

The two gates are run by phase2-gate-evaluator.service.ts. They're separate rows, separate evaluations, with separate thresholds. A proposal can pass one and fail the other — that's a real outcome the operator needs to see.

Gate 1 — synthetic

Reads the latest LearningSyntheticBatch + quality scores. PASS if acceptedCount / caseCount ≥ policy.minQualityThreshold. Writes a LearningProposalGateResult with gate_id='synthetic'.

Gate 2 — replay

Reads the latest LearningReplayRun + results. PASS if passedCount / caseCount ≥ the configured replay threshold. Writes a LearningProposalGateResult with gate_id='replay'.

proposal.gate1ResultId

Denorm pointer to the most recent Gate 1 row.

proposal.gate2ResultId

Denorm pointer to the most recent Gate 2 row.

proposal.status

STAYS 'minted' throughout. Gate results live on LearningProposalGateResult, not on the proposal's status field.

Every $-spending Phase 2 operation (Tier B generation, future Tier C) writes a row to LearningPlaneBudgetWithdrawal AND increments the budget'sspent_micros column. The validation-cost service then re-aggregates from source.

refreshValidationCost(proposalId)

Refresh-from-source. Idempotent: same totals on re-run. Sums withdrawals + synthetic batch costs + replay run costs scoped to this proposal.

totalValidationCostMicros

Sum of all costs incurred validating this proposal, in USD micros.

caseCountSynthetic

Number of synthetic cases that contributed to validation.

caseCountReplay

Number of replay-run cases that contributed.

runCount

Number of replay runs attempted for this proposal.

proposal.validationCostMicros

Denorm of totalValidationCostMicros. Updated after every refresh.

proposal.lastValidatedAt

Timestamp of the most recent refresh. Drives the "stale validation" flag in admin.

Three synthetic generators, each with a different cost / quality / risk profile. The orchestrator dispatches based on policy.tier.

Tier A — template

Deterministic JSON-template permutation generator. FREE (cost = 0). Bounded by maxCasesPerBatch. The default for any policy that doesn't need open-ended generation.

Tier B — cheap-model

Calls a cheap upstream model (e.g. Moonshot Kimi 2.5) via OpenRouter to produce synthetic cases. Mock-mode default — opt in to live via LEARNING_TIER_B_LIVE=true + OPENROUTER_API_KEY. Budget hard-bounded by policy.maxCostPerBatchMicros; the orchestrator debits BEFORE the upstream call. Output flows through the SAME quality-score + replay pipeline as Tier A.

Tier C — frontier

Scaffolding only. Disabled in Phase 2. Four independent gates refuse it: (1) schema default enabled=false, (2) orchestrator approvedByUserId check, (3) orchestrator hard-throw on tier==='C', (4) the generator file itself throws unconditionally. Phase 3+ work; do not enable.

One service guards every $-spending operation: budget-enforcer.service.ts. Uses Postgres SELECT FOR UPDATE to serialise debits across concurrent workers, idempotency keys to prevent retry duplication, and an append-only audit row (LearningPlaneBudgetWithdrawal) as the only evidence of spend.

debitBudget(input)

Returns {withdrawalId, freshDebit}. freshDebit=false means the idempotency key matched an existing row — no second debit happened.

BudgetExceededError

Thrown when budget.budgetMicros - budget.spentMicros < amountMicros. The operation never runs; no audit row written.

idempotencyKey

Caller-supplied string. Format: synthgen:synth:{proposalId}:{policyId}:{windowKey}. Same key = same withdrawal id.

ensureBudgetsForWindow()

Idempotent boot routine. Ensures one LearningPlaneBudget row exists per category per current month-window.

These eight constraints are asserted by every Phase 2 test, every smoke section, and the orchestrator code paths themselves. If any of them ever fails, treat it as a P0 incident.

1. proposal.status stays 'minted' through every operation.
2. No approve / no reject (no writes to approvedByUserId / rejectReason / approvedAt).
3. No publish / no promote (no manifest write path).
4. No manifest (proposal.manifestId stays null).
5. No rollout / no rollback (not implemented in Phase 2).
6. No runtime mutation (zero writes to smart_router_* / llm_call_logs / dispatch surfaces).
7. No live cheap-model promotion (Tier B mock-mode default; live opt-in never wired to dispatch).
8. Tier C disabled — four independent gates fire.

POST /v1/chat/completions

OpenAI-shaped

Standard chat completions. Pass x-tokenone-conversation-id for thread continuity.

POST /v1/messages

Anthropic-shaped

Anthropic Messages API shape. Same routing, same ledger.

POST /v1/google/generateContent

Google-shaped

Gemini-shaped endpoint. Same routing, same ledger.

GET /v1/models

catalogue

Returns the catalogue of models eligible for routing under your tenant.

GET /health

Liveness probe. Always 200 if the API is up.

GET /api/tenant/wallet

Returns current balance, reserved, debited, runway in days.

POST /api/tenant/wallet/topup

Initiate a Stripe top-up. Body: { amountMicros }.

GET /api/tenant/ledger

Paginated ledger entries. Filterable by date, type, project.

GET /api/tenant/ledger/verify

Walks the chain. Returns { verified: bool, firstBroken: string | null }.

GET /api/tenant/baseline

Returns the currently-selected benchmark provider key.

PATCH /api/tenant/baseline

Update the benchmark provider. Body: { providerKey: 'anthropic' | 'openai' | ... }.

GET /api/tenant/insights/overview

The Executive Health response — every tile on /overview comes from this one call.

GET /api/tenant/insights/activity

Live activity feed. Supports search, project filter, channel filter.

GET /api/tenant/insights/usage

Usage rollups: per task family, per project, per hour.

GET /api/tenant/insights/savings

Per-day actual vs baseline-equivalent series.

GET /api/tenant/insights/audit

Decision summaries + change log + export log.

GET /api/users/me

Current user's profile. Includes timezone, bio, avatarUrl, emailVerifiedAt.

PATCH /api/users/me

Update profile fields. Validates against the same Zod schema the UI uses.

GET /api/users/me/sessions

All active sessions for this user.

DELETE /api/users/me/sessions/:id

Revoke a session. Forces refresh-token invalidation immediately.

POST /api/auth/refresh

Refresh the 15-minute access token using the 7-day refresh token.

GET /api/admin/learning/proposals

List minted proposals. Filterable by status, priority, source signal.

GET /api/admin/learning/proposals/:id

Full proposal detail incl. all gate-result rows + cost summary + synthetic batch summary.

GET /api/admin/learning/proposals/:id/synthetic

List synthetic batches + cases for this proposal.

GET /api/admin/learning/proposals/:id/replay

List replay runs + results for this proposal.

GET /api/admin/learning/proposals/:id/gates

Gate evaluation history — both Gate 1 and Gate 2 rows.

GET /api/admin/learning/proposals/:id/cost

Validation cost summary + breakdown.

GET /api/admin/learning/budget

Per-window budget rows with spent / available.

PATCH /api/admin/learning/budget/:id

Set the budget for a category in the current window. Auditable.

id

UUID

Row id. Stable; surfaces on activity-feed deep links.

tenantId

UUID

Owner tenant. Always your tenant on customer-facing views.

projectId

UUID?

Which project the entry attributes to. Nullable for tenant-wide events like top-ups.

eventType

enum (internal)

WALLET_TOPUP / AI_USAGE / REFUND / ADJUSTMENT. The customer view maps these to plain labels.

customerLabel

string

The plain-English label rendered in /settings/ledger. Locked vocabulary: Top-up / AI usage / Refund / Adjustment.

amountMicros

BigInt signed

Tokens debited (negative) or credited (positive). BigInt — strings at the API edge.

balanceAfterMicros

BigInt

Wallet balance after this entry was applied. Lets the inspector show a running balance without server-side recomputation.

modelId

string?

Internal-only. Which model the call routed to. Visible in admin / audit, scrubbed from customer-facing surfaces by policy.

providerKey

string?

Same — internal only.

benchmarkProvider

string?

The brand against which benchmark-equivalent burn was computed for this row.

benchmarkMethodologyVersion

string?

Version of the savings math used. Lets historic rows survive future methodology changes.

actualCostUsdMicros

BigInt?

Real USD cost of this row, in micros (1e6). Internal — feeds the ML learning plane.

baselineCostUsdMicros

BigInt?

What this would have cost at the benchmark provider's pricing. Internal.

benchmarkPricingVersion

string?

Version of the price book used. Future rows can use a newer book; historic rows keep the old one.

sealHash

hex

HMAC-SHA256 over (prevHash + canonicalised payload). The chain anchor.

prevHash

hex

The previous entry's seal hash. Mutating any entry invalidates every entry below it.

createdAt

timestamp

Server-stamped. Drives ordering + windowed queries.

The verify endpoint walks the ledger window in order. For each row, it recomputes HMAC(prevHash + canonicalPayload, LEDGER_HMAC_KEY) and compares it against the stored sealHash. The first mismatch is reported as firstBroken; everything below that row is suspect.

Tokens saved

absolute count

Tokens TokenOne governed delivery preserved vs the benchmark provider. Replaces "Saved", "Saved this month", "Saved 30d".

% saved

ratio

Tokens saved as a share of benchmark-equivalent burn. Replaces "Saved %", "savings %".

Benchmark provider

brand

The customer-selected provider whose pricing is the comparison anchor. Replaces "baseline brand", "baseline model", "default model".

TokenOne burn

tokens

Real tokens consumed via TokenOne governed delivery — naming the actor instead of "Actual". Replaces "Actual burn" (retired 2026-05-27).

<Provider>-equivalent burn

tokens

What the same workload would have cost at the chosen benchmark provider's pricing. Renders parametrically as e.g. "Anthropic-equivalent burn", "OpenAI-equivalent burn"; falls back to "Benchmark-equivalent burn" when no provider is selected. Replaces "Baseline-equivalent burn" (retired 2026-05-27).

1. Provider-led, never model-led. Customers never see model identifiers (kimi-k2.5, gpt-4o, etc.) in primary copy. The benchmark is always a brand: OpenAI, Anthropic, Google, xAI, Meta.
2. Empty state is honest. When tenants.baseline_provider_key is null, the chart shows "Set your benchmark provider to see savings" — never a faked 0% comparison.
3. Audit columns are internal. benchmark_provider, benchmark_methodology_version, actual_cost_usd_micros, baseline_cost_usd_micros, benchmark_pricing_version on llm_call_logs are explainability fields for admins + the ML-learning plane — never rendered to customers.
4. Adding a provider = registering it in BRAND_REGISTRY in the cost-defaults section + mirroring it in baseline-pricing.service.ts. Both registries must stay in sync.
5. Historical rows don't change benchmark. Changing the picker applies to NEW calls. Historic rows keep the benchmark they were attributed to at the time.