llm_cost_tracker 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5d394087953583d254479b4fe162adbb5b5a0f4de09c535428d514a6c623e76
-  data.tar.gz: b3269262ceec2e1f622780e3e44ac33adb1df703e077bee43fcddd7c251a21dc
+  metadata.gz: 357a557efba70db48baf47dde01b0aec7ee8f17787c09276a608572037e1b405
+  data.tar.gz: dd91244e99ecbc531d592572ea419a6567d51980f1f95f9eedb0a929f52ffb71
 SHA512:
-  metadata.gz: 93ce84108bea091e89df70b28a192e280a1e3de92bdb14b8d47ca4057527ebcd4ec1ffa25fc37fc5216df4804539f5b1b9483d6f1fb1afdd292fd19e836431e5
-  data.tar.gz: f69fed55512f322118e93493b9069821e3cd9b372940b6163b7f80578afc3b95799126b91178b25125c7eba871ebe8b3a8fd32e607f8103649c1f3d4d606923d
+  metadata.gz: a9ef38be029273bb2df21e9837e92d166ccb3c931c859437a3e5ace57daebbfaf78db182b93a87aedd9be1df18ef26937cae47b3382a61489fe1e4b1cdd0b669
+  data.tar.gz: 852695ad7b07962ad540b16669e285324b1af5059e975ca645aa2670f8ed5069640e06207a06f170edcdfc19a22e9aacdab684caf831feaa7c334a3d52f41a67

data/.ruby-version

@@ -0,0 +1 @@
+3.4.5

data/CHANGELOG.md

@@ -2,7 +2,78 @@
 
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.8.0] - 2026-05-07
+
+0.8 is a storage rebuild. Tokens and tool/runtime charges share one shape
+(`Billing::LineItem`) and live in a dedicated line items table. Per-component
+cost columns and the standalone service charges table are gone. Several tables
+were also renamed during the cycle. See [Upgrading](docs/upgrading.md) for the
+migration path — there is no rolling-deploy upgrade.
+
+### Added
+
+- `llm_cost_tracker_call_line_items` — one row per priced component (text/audio/cached tokens, web search, code execution, grounding, container sessions, file search). Tokens and tool charges share one shape and one `cost_status` semantics.
+- `llm_cost_tracker_call_tags` — normalized attribution. Tag filters and aggregations now JOIN through this table on PostgreSQL and MySQL alike.
+- `llm_cost_tracker_provider_invoices` — placeholder table reserved for v0.9 invoice reconciliation.
+- `Billing::LineItem` value object covering both token and service charges. `LineItem.from_token_usage` and explicit `component_key:` builders price token and tool/runtime quantities through the same path.
+- `Pricing.price_line_items` — single pricing pass for token + tool/runtime line items, used by `Tracker.build_event`.
+- Doctor schema checks for `llm_cost_tracker_call_line_items`, `llm_cost_tracker_call_tags`, and `llm_cost_tracker_provider_invoices`.
+- Doctor sample-based drift checks: header `total_cost` vs `SUM(line_items.cost)` and stored line item cost vs `pricing_snapshot.rates` (RFC §Doctor).
+- `currency` column on `llm_cost_tracker_call_rollups` (default `USD`) with a `(period, period_start, currency)` unique index. v0.8 stays single-currency; the schema is in place so v0.9 multi-currency rollups don't need another migration.
+- `Billing::Components::REGISTRY` now loads from `lib/llm_cost_tracker/billing/components.yml`. Adding a billable component is one YAML row plus a price entry — no more 11-line `Component.new(...)` literals.
+- Anthropic web search and code execution usage emitted as line items with `component_key: :web_search_request` / `:code_execution_request`. SDK integration emits the same line items from native SDK responses, not just Faraday-wrapped ones.
+- OpenAI hosted web search, file search, and Code Interpreter container sessions emitted as line items via both Faraday and SDK integration paths.
+- Gemini grounding queries emitted as line items.
+- `provider_project_id`, `provider_api_key_id`, `provider_workspace_id`, `batch` capture dimensions on `LlmCostTracker.track` and the `Event` payload, persisted as columns on `llm_cost_tracker_calls`.
+- `Pricing::EffectivePrices` permutes compound pricing modes (e.g. `priority_batch_data_residency`) when matching rates, so combined modes resolve correctly.
+- `Pricing::Sync` registry-diff compares `service_charges` rates in addition to model rates.
+- Dashboard polish pass: shared `_filters.html.erb` and `_sort.html.erb` partials, sticky table headers, button hover/active states, spacing/shadow scales, and a full `prefers-color-scheme` dark palette.
+- Bundled audio and tool rates refreshed from current provider pricing.
+
+### Changed
+
+- BREAKING: Renamed `llm_api_calls` → `llm_cost_tracker_calls`, `llm_cost_tracker_period_totals` → `llm_cost_tracker_call_rollups`, `llm_cost_tracker_inbox_events` → `llm_cost_tracker_ingestion_inbox_entries`, `llm_cost_tracker_ingestor_leases` → `llm_cost_tracker_ingestion_leases`. Corresponding model `LlmCostTracker::PeriodTotal` renamed to `LlmCostTracker::CallRollup`; ingestion models live under `LlmCostTracker::Ingestion::InboxEntry` and `LlmCostTracker::Ingestion::Lease`.
+- BREAKING: Per-component cost columns removed from `llm_cost_tracker_calls` (`input_cost`, `output_cost`, `cache_read_input_cost`, `cache_write_input_cost`, `cache_write_extended_input_cost`, `cache_write_1h_input_cost`, `audio_input_cost`, `audio_output_cost`). The header keeps `total_cost` only; per-component costs live in line items.
+- BREAKING: `llm_cost_tracker_calls.tags` JSONB column removed in favor of `llm_cost_tracker_call_tags`. `Call#parsed_tags`, `Call.by_tags`, `Call.cost_by_tag`, `Call.group_by_tag`, and the dashboard tag explorer now read the normalized table.
+- BREAKING: `llm_cost_tracker_service_charges` table removed. Tool/runtime rows are stored in `llm_cost_tracker_call_line_items` with `unit != 'token'`.
+- BREAKING: `Billing::ServiceCharge` value object and `LlmCostTracker::ServiceCharge` AR model removed. Use `Billing::LineItem` and `LlmCostTracker::CallLineItem`.
+- BREAKING: `Event#service_charges` removed. Filter `event.line_items` by `unit != :token` instead.
+- BREAKING: `Call#service_charges` association removed. Use `call.line_items.where.not(unit: "token")`.
+- BREAKING: `LlmCostTracker.track(service_charges:)` keyword renamed to `service_line_items:`. Hash keys: `component:` → `component_key:`, `source_key:` → `provider_field:`, `pricing_basis: PROVIDER_USAGE_BASIS` → `pricing_basis: :provider_usage`.
+- BREAKING: `Billing::CostStatus.call(service_charges:)` keyword renamed to `service_line_items:`.
+- BREAKING: `Pricing.cost_with_service_charges` public API removed; replaced internally by `Pricing.price_line_items`.
+- BREAKING: Top-level delegators `LlmCostTracker.flush!`, `LlmCostTracker.shutdown!`, `LlmCostTracker.enforce_budget!` removed. Use `LlmCostTracker::Ingestion::Worker.flush!` / `.shutdown!` directly; budget enforcement is internal.
+- BREAKING: `LlmCostTracker.track` requires explicit `tokens:` and accepts `tags:` as a hash; the previous keyword shape is no longer supported.
+- BREAKING: Notification payload (`llm_request.llm_cost_tracker`) no longer carries `service_charges`. Subscribers read `line_items`.
+- BREAKING: Inbox payload v0/v1 compatibility dropped; only v2 is accepted. Drain any pre-v2 entries on the prior gem version before bumping.
+- BREAKING: Ruby 3.4+ required.
+- BREAKING: Legacy upgrade generators removed (`add_billing`, `add_ingestion`, `add_call_rollups`, `add_capture_dimensions`, `add_latency_ms`, `add_provider_response_id`, `add_streaming`, `add_token_usage`, `upgrade_cost_precision`, `upgrade_schema_foundation`, `upgrade_tags_to_jsonb`). Doctor no longer suggests them.
+- `llm_cost_tracker_call_tags.value` widened to TEXT (was VARCHAR), and the `[:key, :value]` composite index dropped in favor of `:key` only — value-equality filters scan the per-key bucket.
+- `Configuration#pricing_overrides` validates shape at assignment time rather than at first read.
+- Pricing computes a partial `total_cost` (with `cost_status: :partial`) when only some token components have rates; previously `total_cost` was nil whenever any component lacked a rate.
+- `TokenUsage.build` clamps negative token counts to zero so anomalous provider payloads don't poison rollups.
+- Stream collector buffer overflow keeps already-accumulated events instead of dropping them.
+- Budget guardrail preflight time is excluded from SDK call latency measurements.
+- Dashboard data-quality breakdown computes per-component cost from line items via JOIN; usage_rows accepts `component_costs:` hash.
+- CSV export pulls tag JSON from `tag_records` instead of the dropped JSONB column.
+- The fingerprinted dashboard stylesheet is served with `Cache-Control: no-store` in development so edits show up without a hard reload; production keeps the immutable cache.
+
+### Fixed
+
+- Railtie no longer requires removed legacy upgrade generators at boot, so installs on a clean app don't crash during eager-load.
+- `Tracker` only flags unknown pricing when token quantities are positive — service-only events with zero tokens no longer raise `Pricing::Unknown`.
+- `Billing::CostStatus.cost_status_for` coerces symbol/string status values consistently when building line items.
+- Gemini `thoughtsTokenCount` is billed at the output token rate (already present in 0.7.3, kept for clarity given the rebuild).
+
+### Removed
+
+- Dead `Billing::LineItem.from_service_charge` constructor and the unused `Call.with_json_tags` scope.
+
+## [0.7.3] - 2026-05-01
+
+### Fixed
+
+- Gemini API thinking tokens no longer get added to output tokens twice.
 
 ## [0.7.2] - 2026-05-01
 

data/README.md

@@ -1,46 +1,46 @@
 # LLM Cost Tracker
 
-A Rails-native ledger for what your LLM calls actually cost.
+Self-hosted LLM cost tracking for Rails.
 
 [![Gem Version](https://img.shields.io/gem/v/llm_cost_tracker.svg)](https://rubygems.org/gems/llm_cost_tracker)
 [![CI](https://github.com/sergey-homenko/llm_cost_tracker/actions/workflows/ruby.yml/badge.svg)](https://github.com/sergey-homenko/llm_cost_tracker/actions)
 [![codecov](https://codecov.io/gh/sergey-homenko/llm_cost_tracker/branch/main/graph/badge.svg)](https://codecov.io/gh/sergey-homenko/llm_cost_tracker)
 
-If you have OpenAI, Anthropic, or Gemini in production and someone keeps asking "where did that bill come from?", this gem records every call into your own database, prices it locally, and gives you a dashboard you can mount in five minutes. No proxy, no SaaS account, no extra service to deploy.
+Every call your app makes to OpenAI, Anthropic, Gemini, RubyLLM, or any
+OpenAI-compatible API gets logged: tokens, cost, latency, tags. Calls go
+app → provider direct. No proxy.
 
-It is not Langfuse, Helicone, or LiteLLM. It does not capture prompts, score completions, or replay traces. It does one thing: tells you which provider, which model, which feature, and which user burned how much money. That's the entire pitch.
+Not Langfuse, Helicone, or LiteLLM. No prompts, no traces, no replay. Spend
+attribution only.
 
-Requires Ruby 3.3+, Rails 7.1+, PostgreSQL or MySQL, and Faraday 2.0+.
+Requires Ruby 3.4+, Rails 7.1+, PostgreSQL or MySQL.
 
 ![Dashboard overview](docs/dashboard-overview.png)
 
 ## Quickstart
 
-Add to your Gemfile alongside whatever LLM client you already use:
-
 ```ruby
+# Gemfile
 gem "llm_cost_tracker"
-gem "openai"  # or "anthropic", "ruby_llm", or your existing client
+gem "openai"
 ```
 
-Install, migrate, verify:
-
 ```bash
-bin/rails generate llm_cost_tracker:install --dashboard --prices
-bin/rails db:migrate
-bin/rails llm_cost_tracker:doctor
+bin/rails llm_cost_tracker:setup
 ```
 
-Drop this into `config/initializers/llm_cost_tracker.rb`:
+That runs the install generator with the dashboard and pricing snapshot,
+migrates the database, then verifies via `llm_cost_tracker:doctor`.
 
 ```ruby
+# config/initializers/llm_cost_tracker.rb
 LlmCostTracker.configure do |config|
   config.default_tags = -> { { environment: Rails.env } }
   config.instrument :openai
 end
 ```
 
-Now every OpenAI call is recorded. Wrap calls in `with_tags` to attribute spend to a user, feature, or anything else you care about:
+Tag your calls — that's how you find out who burned the money:
 
 ```ruby
 LlmCostTracker.with_tags(user_id: Current.user&.id, feature: "chat") do
@@ -49,240 +49,77 @@ LlmCostTracker.with_tags(user_id: Current.user&.id, feature: "chat") do
 end
 ```
 
-Visit `/llm-costs` for the dashboard. **Mount it behind your app's auth before deploying** — the gem doesn't ship with one, on purpose.
-
-## What you get
-
-- Local ActiveRecord ledger of every call: provider, model, token breakdown, cost, latency, tags, response IDs
-- Auto-capture for RubyLLM and the official `openai` and `anthropic` Ruby SDKs, plus Faraday middleware for `ruby-openai`, the Gemini REST API, and any client you can inject middleware into
-- Server-rendered dashboard (plain ERB, zero JavaScript) with overview, models, calls, tags, CSV export, and a data-quality page
-- Local pricing snapshots refreshed daily from the official provider pricing pages, applied with `bin/rails llm_cost_tracker:prices:refresh`
-- Monthly / daily / per-call budget guardrails with notify, raise, or block-requests behaviour
-- Tag-based attribution that survives concurrency — Puma threads and Sidekiq fibers don't bleed into each other
-
-## What it deliberately doesn't do
-
-- **Doesn't run as a proxy.** Calls go directly from your app to the provider.
-- **Doesn't store prompts or completions.** Token counts, model, cost, tags, response IDs only. Nothing else.
-- **Doesn't promise invoice-grade accuracy.** It uses official provider pricing pages, but enterprise rates, batch discounts on unsupported endpoints, and modality tiers are not always modeled. `provider_response_id` is stored as a join key for whoever does that reconciliation.
-- **Doesn't ship with auth on the dashboard.** It's a Rails Engine; mount it behind whatever your app already uses (Devise, basic auth, Cloudflare Access, your own session middleware).
-- **Doesn't centralize multi-service visibility.** One Rails monolith — perfect fit. Six services in four languages — wrong tool, look at a proxy or API-layer gateway.
-
-## Capturing calls
-
-Three paths, in order of preference. Use the first one that fits your stack.
-
-### 1. SDK integrations
-
-Drop-in for RubyLLM and the official `openai` and `anthropic` gems. `config.instrument` patches tested SDK methods so you don't change a single call site:
-
-```ruby
-LlmCostTracker.configure do |config|
-  config.instrument :openai # or :anthropic / :ruby_llm
-end
-
-LlmCostTracker.with_tags(feature: "support_chat") do
-  Anthropic::Client.new.messages.create(
-    model: "claude-sonnet-4-6",
-    max_tokens: 1024,
-    messages: [{ role: "user", content: "Hello" }]
-  )
-end
-```
-
-Captures usage, model, latency, response ID, pricing mode, cache tokens, Anthropic cache-write TTLs, and reasoning tokens whenever the SDK exposes them. Provider SDKs are not added as gem dependencies — you install whichever you actually use.
-
-Enabled integrations are checked at boot: the client gem must be loaded, meet the minimum supported version, and expose the expected classes and methods. If the contract check fails, boot raises instead of silently missing spend.
+Mount the dashboard at `/llm-costs` and put it behind your app's auth — it
+ships without one.
 
-This patches **only** RubyLLM and the official Ruby SDKs. `ruby-openai` (alexrudall) and any custom client go through Faraday middleware below.
+## What lands in the ledger
 
-### 2. Faraday middleware
+- **Calls.** Provider, model, total tokens, total cost, latency, status.
+- **Line items.** Per-component breakdown — text/audio/cached tokens, tool
+  charges (web search, code execution, grounding, container sessions).
+- **Tags.** Whatever attribution you pass — user, feature, tenant, env.
+- **Provider IDs.** Response, project, API key, workspace — for downstream
+  audits.
+- **Pricing snapshot.** So historical numbers don't drift when prices change.
 
-For `ruby-openai`, the Gemini REST API, custom Faraday clients, or anything OpenAI-compatible (OpenRouter, DeepSeek, Groq, LiteLLM proxies):
+## Capture surfaces
 
-```ruby
-conn = Faraday.new(url: "https://api.openai.com") do |f|
-  f.use :llm_cost_tracker, tags: -> { { feature: "chat", user_id: Current.user&.id } }
-  f.request :json
-  f.response :json
-  f.adapter Faraday.default_adapter
-end
-```
+| Surface | Path |
+| --- | --- |
+| OpenAI | Official SDK or Faraday |
+| Anthropic | Official SDK or Faraday |
+| Google Gemini | Faraday |
+| RubyLLM | Provider layer |
+| `ruby-openai` | Faraday |
+| OpenRouter, DeepSeek, Groq, LiteLLM-style gateways | OpenAI-compatible Faraday |
+| Anything else | `LlmCostTracker.track` |
 
-Tags can be a hash or a callable evaluated per request. Place the middleware where it sees the final response body — in practice, before the JSON parser.
+Streams capture when the provider emits final usage. OpenAI Faraday streams
+need `stream_options: { include_usage: true }`.
 
-Streaming works through the same path: the middleware tees the `on_data` callback so your code keeps receiving chunks normally, and the final usage gets recorded once the stream finishes. OpenAI streams need `stream_options: { include_usage: true }` for the final usage event.
+## What it isn't
 
-Per-client setup snippets for `ruby-openai`, Azure OpenAI, LiteLLM proxy, and Gemini live in [`docs/cookbook.md`](docs/cookbook.md).
+- No proxy. Direct calls only.
+- No prompts. Token counts and metadata only.
+- Not invoice-grade. Provider response IDs are stored for reconciliation.
+- Not multi-service. Built for a Rails monolith.
 
-### 3. Manual `track` / `track_stream`
+## Manual tracking
 
-When you have a client that doesn't expose Faraday and isn't an official SDK — internal gateways, homegrown wrappers, batch jobs replaying historical usage:
+For batch jobs, internal gateways, or anything without an SDK/Faraday hook:
 
 ```ruby
 LlmCostTracker.track(
   provider: :anthropic,
   model: "claude-sonnet-4-6",
-  input_tokens: 1500,
-  output_tokens: 320,
-  feature: "summarizer",
-  user_id: current_user.id
+  tokens: { input: 1500, output: 320 },
+  tags: { feature: "summarizer", user_id: current_user.id }
 )
 ```
 
-For streaming the same way, `track_stream` accepts a block, parses provider events automatically, and records once the stream finishes. Full reference in [`docs/streaming.md`](docs/streaming.md).
-
-## Tags: who burned this money
-
-Tags answer the only question that matters in attribution: which feature, which user, which job, which tenant. They're free-form strings, stored as JSONB on PostgreSQL or JSON on MySQL, and queryable from both Ruby and the dashboard.
-
-```ruby
-LlmCostTracker.with_tags(user_id: current_user.id, feature: "support_chat") do
-  client.chat(parameters: { model: "gpt-4o", messages: [...] })
-end
-```
-
-`with_tags` is thread- and fiber-isolated, so concurrent requests in Puma or jobs in Sidekiq don't bleed into each other. A `default_tags` callable on configuration runs on every event for things you always want — `environment`, `region`, deployment SHA. Explicit tags passed to `track` win over scoped tags, scoped tags win over defaults.
-
-Streaming capture snapshots tags when the stream starts, so attribution survives delayed or cross-thread stream consumption.
-
-What you put in tags is **your** input — they're queryable strings. Don't put prompts, completions, emails, or secrets there. Use IDs.
-
-## Pricing
-
-Built-in prices live in `lib/llm_cost_tracker/prices.json` and are refreshed daily from official provider pricing pages by an automated CI workflow that opens a PR on every change. Most apps run on bundled prices and never think about this.
-
-When you want to control updates yourself — for negotiated rates, gateway-specific model IDs, or pinned reviews — generate a local snapshot:
-
-```bash
-bin/rails generate llm_cost_tracker:prices
-```
-
-```ruby
-config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
-```
-
-Refresh on demand from the maintained snapshot:
-
-```bash
-bin/rails llm_cost_tracker:prices:refresh
-```
-
-Explain why a model is priced or unknown:
-
-```bash
-PROVIDER=openai MODEL=gpt-4o bin/rails llm_cost_tracker:prices:explain
-```
-
-Precedence is `pricing_overrides` → `prices_file` → bundled. Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys.
-
-`pricing_mode` selects mode-prefixed rates such as `batch_input` or `priority_output`. Built-in capture fills it from provider tier fields when available; explicit `track` calls can pass it directly for batch jobs or gateway-specific modes. Full pricing reference: [`docs/pricing.md`](docs/pricing.md).
-
-## Budgets
-
-Budgets are guardrails, not transactional caps:
-
-```ruby
-config.monthly_budget           = 500.00
-config.daily_budget             = 50.00
-config.per_call_budget          = 2.00
-config.budget_exceeded_behavior = :block_requests # or :notify, :raise
-config.on_budget_exceeded       = ->(data) { SlackNotifier.notify("#alerts", "...") }
-```
-
-`:block_requests` reads ledger totals before a call goes out and stops it if you're already over. Under concurrency multiple workers can pass preflight at the same time and collectively overshoot — this catches the next call after the overshoot becomes visible, not the overshoot itself. For a strict cap, use a provider-side limit or a transactional counter outside the gem.
-
-Full behavior, error class, and preflight details: [`docs/budgets.md`](docs/budgets.md).
+## Docs
 
-## Querying
-
-When you want to slice spend from a console, scheduled job, or your own admin page:
-
-```ruby
-LlmCostTracker::Ledger::Call.this_month.cost_by_model
-LlmCostTracker::Ledger::Call.this_month.cost_by_tag("feature")
-LlmCostTracker::Ledger::Call.daily_costs(days: 7)
-LlmCostTracker::Ledger::Call.by_tags(user_id: 42, feature: "chat").this_month.total_cost
-```
-
-A text report is also one rake task away:
-
-```bash
-DAYS=7 bin/rails llm_cost_tracker:report
-```
-
-Full scope and helper reference: [`docs/querying.md`](docs/querying.md).
-
-## Dashboard
-
-Mount the engine wherever you want — it's plain ERB, no JavaScript bundle, no asset pipeline gymnastics:
-
-```ruby
-# config/routes.rb
-mount LlmCostTracker::Engine => "/llm-costs"
-```
-
-Pages: overview (spend trend, budget status, anomaly banner), models, calls (filterable, paginated, CSV export), tags, data quality. Reads the ActiveRecord ledger in `llm_api_calls`.
-
-Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs/dashboard.md).
-
-## Supported providers
-
-| Provider | Auto-detected | Coverage |
-|---|:---:|---|
-| OpenAI | Yes | GPT-5.5/5.4/5.2/5.1/5 + pro/mini/nano variants, GPT-4.1, GPT-4o, o1/o3/o4-mini |
-| Anthropic | Yes | Claude Opus 4.7/4.6/4.5/4.1/4, Sonnet 4.6/4.5/4, Haiku 4.5 |
-| Google Gemini | Yes | Gemini 2.5 Pro/Flash/Flash-Lite, 2.0 Flash/Flash-Lite |
-| OpenRouter | Yes | OpenAI-compatible usage; provider-prefixed model IDs are normalized |
-| DeepSeek | Yes | OpenAI-compatible usage; add `pricing_overrides` for DeepSeek-specific rates |
-| Groq | Yes | OpenAI-compatible usage with bundled prices for production text models |
-| Other OpenAI-compatible hosts | Configurable | Register the host via `config.openai_compatible_providers` |
-| Anything else | Manual | Use `LlmCostTracker.track` / `track_stream` |
-
-RubyLLM chat, embedding, and transcription calls are captured through RubyLLM's provider layer when `config.instrument :ruby_llm` is enabled.
-
-Endpoints covered end-to-end: OpenAI Chat Completions / Responses / Completions / Embeddings, Anthropic Messages, Gemini `generateContent` and `streamGenerateContent`, plus their OpenAI-compatible equivalents. Streaming is captured for Faraday paths and official OpenAI / Anthropic SDK stream helpers whenever the provider emits final-usage events.
-
-## Privacy
-
-By design, **no prompt or response content is ever stored.** Per call, the ledger holds: provider, model, token counts, cost, latency, tags, response ID, timestamp. That's it. No request bodies, no headers, no completions. Warning logs strip query strings before logging URLs.
-
-Tags carry whatever your app passes — they are application-controlled input, treat them accordingly. Use `user_id`, not the user's email; use a feature key, not the input prompt.
-
-## Documentation
-
-Deeper guides live in `docs/`. Reference pages are being filled out as content
-moves out of this README; the inline sections above remain canonical where a page
-is still brief.
-
-- [Configuration reference](docs/configuration.md)
-- [Pricing & price refresh](docs/pricing.md)
-- [Budgets & guardrails](docs/budgets.md)
-- [Querying & reports](docs/querying.md)
-- [Dashboard mounting](docs/dashboard.md)
-- [Streaming capture](docs/streaming.md)
+- [Configuration](docs/configuration.md)
+- [Pricing](docs/pricing.md)
+- [Budgets](docs/budgets.md)
+- [Data model](docs/data-model.md)
+- [Querying](docs/querying.md)
+- [Dashboard](docs/dashboard.md)
+- [Streaming](docs/streaming.md)
+- [Cookbook](docs/cookbook.md)
 - [Extending](docs/extending.md)
-- [Production operations](docs/operations.md)
+- [Operations](docs/operations.md)
+- [Architecture](docs/architecture.md)
 - [Upgrading](docs/upgrading.md)
-- [Cookbook — per-client recipes](docs/cookbook.md)
-- [Architecture & design rules](docs/architecture.md)
-
-## Known limitations
-
-- `:block_requests` is best-effort under concurrency, not a transactional cap.
-- Streaming usage capture relies on the provider emitting a final-usage event. Missing events are stored with `usage_source: "unknown"` so they appear on the data-quality page rather than vanishing.
-- Non-token line items such as Gemini explicit-cache storage duration, provider tool calls, and modality-specific surcharges are not folded into token cost.
-- `provider_response_id` is stored only when the provider exposes a stable ID. Gemini is best-effort and varies by endpoint.
+- [Changelog](CHANGELOG.md)
 
 ## Development
 
 ```bash
 bundle install
-bin/check # rubocop + rspec + coverage gate
+bin/check
 ```
 
-Architecture rules and conventions for contributions live in [`docs/architecture.md`](docs/architecture.md).
-
 ## License
 
 MIT — see [LICENSE.txt](LICENSE.txt).