llm_cost_tracker 0.4.1 → 0.5.1

data/README.md

@@ -1,107 +1,103 @@
 # LLM Cost Tracker
 
-**Self-hosted LLM cost tracking for Ruby and Rails.** Intercepts Faraday LLM responses or records usage explicitly, prices events locally, and stores them in your database. No proxy, no SaaS.
+A Rails-native ledger for what your LLM calls actually cost.
 
 [![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)
 
-Requires Ruby 3.3+, Rails/ActiveRecord 7.1+, and Faraday 2.0+.
-Core tracking works without Rails; the mounted dashboard requires Rails 7.1+.
+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.
 
-## Why
+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.
 
-Every Rails app with LLM integrations eventually runs into the same question: where did that invoice come from? Full observability platforms like Langfuse and Helicone solve a broader set of problems; sometimes you just need a small Rails-native ledger in your own database.
+Requires Ruby 3.3+, ActiveSupport 7.1+, Faraday 2.0+. ActiveRecord storage and the dashboard need Rails 7.1+.
 
-## What You Get
-
-- A local ActiveRecord ledger of provider, model, usage breakdown, cost, latency, tags, streaming usage, and provider response IDs
-- Faraday middleware plus explicit `track` / `track_stream` helpers for non-Faraday clients
-- Server-rendered Rails dashboard with overview, calls, tags, CSV export, and data-quality pages
-- Local pricing snapshots, price sync tasks, and budget guardrails
-- Prompt and response bodies are never persisted
-
-## Dashboard
-
-LLM Cost Tracker ships with an optional server-rendered Rails Engine dashboard for spend review, attribution, and data quality checks.
-
-![LLM Cost Tracker dashboard](docs/dashboard-overview.png)
-
-The overview page includes spend trend, budget status, provider breakdown, top models, and filterable slices. The engine also includes Calls, Tags, and Data Quality pages. Plain ERB, no JavaScript bundle.
+![Dashboard overview](docs/dashboard-overview.png)
 
 ## Quickstart
 
+Add to your Gemfile alongside whatever LLM client you already use:
+
 ```ruby
 gem "llm_cost_tracker"
+gem "openai"  # or "anthropic", or your existing client
 ```
 
+Install, migrate, verify:
+
 ```bash
-bin/rails generate llm_cost_tracker:install
+bin/rails generate llm_cost_tracker:install --dashboard --prices
 bin/rails db:migrate
+bin/rails llm_cost_tracker:doctor
 ```
 
+Drop this into `config/initializers/llm_cost_tracker.rb`:
+
 ```ruby
 LlmCostTracker.configure do |config|
   config.storage_backend = :active_record
-  config.default_tags = { app: "my_app", environment: Rails.env }
-end
-
-OpenAI.configure do |config|
-  config.access_token = ENV["OPENAI_API_KEY"]
-  config.faraday do |f|
-    f.use :llm_cost_tracker, tags: -> { { user_id: Current.user&.id, feature: "chat" } }
-  end
+  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:
+
 ```ruby
-mount LlmCostTracker::Engine => "/llm-costs"
+LlmCostTracker.with_tags(user_id: Current.user&.id, feature: "chat") do
+  client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
+  client.responses.create(model: "gpt-4o", input: "Hello")
+end
 ```
 
-After that, LLM Cost Tracker starts recording calls into `llm_api_calls` and the dashboard becomes available at `/llm-costs`.
-Protect the mounted engine with your application's authentication before exposing it outside development.
+Visit `/llm-costs` for the dashboard. **Mount it behind your app's auth before deploying** — the gem doesn't ship with one, on purpose.
 
-## Tradeoffs
+## What you get
 
-- Self-hosted ledger first: no proxy, no SaaS, no separate service to operate
-- Best-effort pricing for spend review and attribution, not invoice-grade billing
-- No prompt or response body storage
-- No built-in auth on the mounted dashboard
-- Use `:active_record` when you want shared dashboards and budget checks across Puma workers and Sidekiq processes
+- Local ActiveRecord ledger of every call: provider, model, token breakdown, cost, latency, tags, response IDs
+- Auto-capture for 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
 
-## Installation
+## What it deliberately doesn't do
 
-```ruby
-gem "llm_cost_tracker"
-```
+- **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.
 
-For ActiveRecord storage:
+## Capturing calls
 
-```bash
-bin/rails generate llm_cost_tracker:install
-bin/rails db:migrate
-```
+Three paths, in order of preference. Use the first one that fits your stack.
 
-## Usage
+### 1. Official SDK integrations
 
-### Patch an existing client's Faraday connection
+Drop-in for the official `openai` and `anthropic` gems. `config.instrument` patches the SDK's resource methods so you don't change a single call site:
 
 ```ruby
-# config/initializers/openai.rb
-OpenAI.configure do |config|
-  config.access_token = ENV["OPENAI_API_KEY"]
-
-  config.faraday do |f|
-    f.use :llm_cost_tracker, tags: -> {
-      { user_id: Current.user&.id, workflow: Current.workflow, env: Rails.env }
-    }
-  end
+LlmCostTracker.configure do |config|
+  config.instrument :openai      # or :anthropic, or :all
+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
 ```
 
-`tags:` can be a callable and is evaluated on each request.
+Captures usage, model, latency, response ID, cache tokens, and reasoning tokens whenever the SDK exposes them. Provider SDKs are not added as gem dependencies — you install whichever you actually use.
 
-### Raw Faraday
+This patches **only** the official Ruby SDKs. `ruby-openai` (alexrudall) and any custom client go through Faraday middleware below.
+
+### 2. Faraday middleware
+
+For `ruby-openai`, the Gemini REST API, custom Faraday clients, or anything OpenAI-compatible (OpenRouter, DeepSeek, LiteLLM proxies):
 
 ```ruby
 conn = Faraday.new(url: "https://api.openai.com") do |f|
@@ -110,60 +106,17 @@ conn = Faraday.new(url: "https://api.openai.com") do |f|
   f.response :json
   f.adapter Faraday.default_adapter
 end
-
-conn.post("/v1/responses", { model: "gpt-5-mini", input: "Hello!" })
-```
-
-Place `llm_cost_tracker` inside the Faraday stack where it can see the final response body.
-
-### Streaming
-
-Streaming is captured automatically for OpenAI, Anthropic, and Gemini when the request goes through the Faraday middleware. The middleware tees the `on_data` callback, keeps the stream flowing to your code, and records the final usage block once the response completes.
-
-```ruby
-# OpenAI: include usage in the final chunk
-client.chat(parameters: {
-  model: "gpt-4o",
-  messages: [...],
-  stream: proc { |chunk| ... },
-  stream_options: { include_usage: true }
-})
-```
-
-Anthropic emits usage in `message_start` + `message_delta` events. Gemini's `:streamGenerateContent` endpoint includes `usageMetadata`; usage from the final chunk is used.
-
-Streamed calls are stored with `stream: true` and `usage_source: "stream_final"`. If the provider never sends final usage, the call is still recorded with `usage_source: "unknown"` so those calls surface on the Data Quality page.
-
-When the provider emits a stable response object ID, LLM Cost Tracker stores it as `provider_response_id`. OpenAI and Anthropic are covered end-to-end; Gemini is best effort and may vary by endpoint or API version.
-
-For non-Faraday clients (raw `Net::HTTP`, custom SSE code, Azure OpenAI), use the explicit helper:
-
-```ruby
-LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o") do |stream|
-  my_client.stream(...) { |chunk| stream.event(chunk) }
-end
-
-# Or skip the chunk parsing entirely if you already know the totals:
-LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o") do |stream|
-  # ... your streaming loop ...
-  stream.usage(input_tokens: 120, output_tokens: 45)
-end
 ```
 
-If your custom streaming client exposes the provider's response object ID after the stream starts, set it explicitly:
+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.
 
-```ruby
-LlmCostTracker.track_stream(provider: "anthropic", model: "claude-sonnet-4-6") do |stream|
-  stream.provider_response_id = response.id
-  stream.usage(input_tokens: 120, output_tokens: 45)
-end
-```
+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.
 
-Run `bin/rails g llm_cost_tracker:add_streaming` once on existing installs to add the `stream` and `usage_source` columns. Run `bin/rails g llm_cost_tracker:add_provider_response_id` to persist provider-issued response IDs. Run `bin/rails g llm_cost_tracker:add_usage_breakdown` to add cache-read, cache-write, hidden-output, and pricing-mode columns.
+Per-client setup snippets for `ruby-openai`, Azure OpenAI, LiteLLM proxy, and Gemini live in [`docs/cookbook.md`](docs/cookbook.md).
 
-More client-specific snippets live in [`docs/cookbook.md`](docs/cookbook.md).
+### 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:
 
 ```ruby
 LlmCostTracker.track(
@@ -171,378 +124,152 @@ LlmCostTracker.track(
   model: "claude-sonnet-4-6",
   input_tokens: 1500,
   output_tokens: 320,
-  provider_response_id: "msg_01XFDUDYJgAACzvnptvVoYEL",
-  cache_read_input_tokens: 1200,
   feature: "summarizer",
   user_id: current_user.id
 )
 ```
 
-`input_tokens` is regular non-cache input. Put cache hits in
-`cache_read_input_tokens` and cache writes in `cache_write_input_tokens`; total
-tokens are calculated from the canonical billing breakdown.
+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).
 
-## Configuration
+## 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, indexed (JSONB on Postgres, fallback elsewhere), and queryable from both Ruby and the dashboard.
 
 ```ruby
-# config/initializers/llm_cost_tracker.rb
-LlmCostTracker.configure do |config|
-  config.storage_backend = :active_record # :log (default), :active_record, :custom
-  config.default_tags = { app: "my_app", environment: Rails.env }
-
-  config.monthly_budget = 500.00
-  config.daily_budget = 50.00
-  config.per_call_budget = 2.00
-  config.budget_exceeded_behavior = :notify  # :notify, :raise, :block_requests
-  config.storage_error_behavior   = :warn    # :ignore, :warn, :raise
-  config.unknown_pricing_behavior = :warn    # :ignore, :warn, :raise
-
-  config.on_budget_exceeded = ->(data) {
-    SlackNotifier.notify("#alerts", "🚨 LLM #{data[:budget_type]} budget $#{data[:total].round(2)} / $#{data[:budget]}")
-  }
-
-  config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
-  config.pricing_overrides = {
-    "ft:gpt-4o-mini:my-org" => { input: 0.30, cache_read_input: 0.15, output: 1.20 }
-  }
-
-  # Built-in: openrouter.ai, api.deepseek.com
-  config.openai_compatible_providers["llm.my-company.com"] = "internal_gateway"
+LlmCostTracker.with_tags(user_id: current_user.id, feature: "support_chat", trace_id: request.uuid) do
+  client.chat(parameters: { model: "gpt-4o", messages: [...] })
 end
 ```
 
-Pricing is best effort. OpenRouter-style IDs like `openai/gpt-4o-mini` are normalized to built-in names when possible. Use `prices_file` / `pricing_overrides` for fine-tunes, gateway-specific IDs, enterprise discounts, alternate pricing modes, or models the gem does not know.
-Provider-specific entries like `openai/gpt-4o-mini` win over model-only entries like `gpt-4o-mini`.
-Pass `pricing_mode: :batch` to use optional mode-specific keys such as `batch_input` / `batch_output`; missing mode-specific keys fall back to standard `input` / `output` rates. The same pattern works for custom modes, for example `contract_input`.
+`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.
 
-`storage_error_behavior = :warn` (default) lets LLM responses continue if storage fails; `:raise` exposes `StorageError#original_error`.
+What you put in tags is **your** input — they're queryable strings. Don't put prompts, completions, emails, or secrets there. Use IDs.
 
-Unknown pricing still records token counts, but `cost` is `nil` and budget guardrails skip that event. Find unpriced models:
+## Pricing
 
-```ruby
-LlmCostTracker::LlmApiCall.unknown_pricing.group(:model).count
-```
+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.
 
-### Keeping prices current
-
-Built-in prices live in `lib/llm_cost_tracker/prices.json`. The gem never fetches pricing on boot. For production, keep a local snapshot under `config/` and point the gem at it:
+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
 ```
 
-```json
-{
-  "metadata": { "updated_at": "2026-04-18", "currency": "USD", "unit": "1M tokens" },
-  "models": {
-    "my-gateway/gpt-4o-mini": { "input": 0.20, "cache_read_input": 0.10, "output": 0.80, "batch_input": 0.10, "batch_output": 0.40 }
-  }
-}
+```ruby
+config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
 ```
 
-`pricing_overrides` has the highest precedence. Use it for a handful of Ruby-side overrides; use `prices_file` when you want a local pricing table under source control.
-
-To refresh prices on demand:
+Refresh on demand from the maintained snapshot:
 
 ```bash
-bin/rails llm_cost_tracker:prices:sync
-```
-
-`llm_cost_tracker:prices:sync` refreshes the current registry from two structured sources: LiteLLM first, OpenRouter second. LiteLLM is the primary source; OpenRouter fills gaps and helps surface discrepancies.
-
-`llm_cost_tracker:prices:sync` / `llm_cost_tracker:prices:check` perform HTTP GET requests to:
-
-- LiteLLM pricing JSON: `https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json`
-- OpenRouter Models API: `https://openrouter.ai/api/v1/models`
-
-If `config.prices_file` is configured, the task syncs that file automatically; otherwise it works from the built-in snapshot. `_source: "manual"` entries are never touched. Models that are still in your file but missing from both upstream sources are left alone and reported as orphaned. For intentional custom entries, mark them as manual so they stop showing up in orphaned warnings.
-
-Use `PREVIEW=1` to see the diff without writing. Use `STRICT=1` to fail instead of applying a partial refresh when a source fails or the validator rejects a price. Use `bin/rails llm_cost_tracker:prices:check` in CI to print the current diff and exit non-zero when the snapshot has drifted or refresh fails.
-
-Large price changes are flagged during sync. If a specific entry is expected to move by more than 3x, add `_validator_override: ["skip_relative_change"]` to that entry in your local price file.
-
-## Budget enforcement
-
-```ruby
-config.storage_backend = :active_record
-config.monthly_budget = 100.00
-config.daily_budget = 10.00
-config.per_call_budget = 1.00
-config.budget_exceeded_behavior = :block_requests
+bin/rails llm_cost_tracker:prices:refresh
 ```
 
-- `:notify` — fire `on_budget_exceeded` after an event pushes the monthly, daily, or per-call budget over the limit.
-- `:raise` — record the event, then raise `BudgetExceededError`.
-- `:block_requests` — block preflight when the stored monthly or daily total is already over budget; still raises post-response on the event that crosses the line. Needs `:active_record` storage for preflight.
+Precedence is `pricing_overrides` → `prices_file` → bundled. Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys. Full pricing reference: [`docs/pricing.md`](docs/pricing.md).
 
-`monthly_budget` and `daily_budget` are cumulative ledger limits. `per_call_budget` is a ceiling for a single priced event and runs after the response cost is known.
+## Budgets
 
-ActiveRecord installs keep `llm_cost_tracker_period_totals` in sync with atomic upserts. Budget preflight reads period rollups instead of scanning `llm_api_calls`.
+Budgets are guardrails, not transactional caps:
 
 ```ruby
-rescue LlmCostTracker::BudgetExceededError => e
-  # e.budget_type, e.total, e.budget, e.monthly_total, e.daily_total, e.call_cost, e.last_event
+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` is a **guardrail, not a hard cap**. The preflight and the spend-recording write are separate statements, so under Puma / Sidekiq concurrency multiple workers can all pass the preflight and then collectively overshoot the budget. The setting reliably *stops new requests after the overshoot is visible* — it does not prevent the overshoot itself. For strict quotas use a provider- or gateway-level limit, or a database-backed counter outside this gem.
-
-Preflight is wired into the Faraday middleware automatically. When you record events via `LlmCostTracker.track` / `track_stream` and also want the same preflight, opt in:
+`: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.
 
-```ruby
-LlmCostTracker.track(
-  provider: "openai",
-  model: "gpt-4o",
-  input_tokens: 120,
-  output_tokens: 45,
-  enforce_budget: true
-)
-
-LlmCostTracker.track_stream(provider: "openai", model: "gpt-4o", enforce_budget: true) do |stream|
-  # raises BudgetExceededError before the block runs when over budget
-end
-
-LlmCostTracker.enforce_budget! # standalone preflight
-```
+Full behavior, error class, and preflight details: [`docs/budgets.md`](docs/budgets.md).
 
-## Querying costs
+## Querying
 
-```bash
-bin/rails llm_cost_tracker:report
-DAYS=7 bin/rails llm_cost_tracker:report
-```
+When you want to slice spend from a console, scheduled job, or your own admin page:
 
 ```ruby
-LlmCostTracker::LlmApiCall.today.total_cost
 LlmCostTracker::LlmApiCall.this_month.cost_by_model
-LlmCostTracker::LlmApiCall.this_month.cost_by_provider
-
-# Group / sum by any tag
-LlmCostTracker::LlmApiCall.this_month.group_by_tag("feature").sum(:total_cost)
-LlmCostTracker::LlmApiCall.this_month.cost_by_tag("feature")  # with "(untagged)" bucket
-
-# Period grouping (SQL-side)
-LlmCostTracker::LlmApiCall.this_month.group_by_period(:day).sum(:total_cost)
-LlmCostTracker::LlmApiCall.group_by_period(:month).sum(:total_cost)
+LlmCostTracker::LlmApiCall.this_month.cost_by_tag("feature")
 LlmCostTracker::LlmApiCall.daily_costs(days: 7)
-
-# Latency
-LlmCostTracker::LlmApiCall.with_latency.average_latency_ms
-LlmCostTracker::LlmApiCall.this_month.latency_by_model
-
-# Tag filters
-LlmCostTracker::LlmApiCall.by_tag("feature", "chat").this_month.total_cost
 LlmCostTracker::LlmApiCall.by_tags(user_id: 42, feature: "chat").this_month.total_cost
-
-# Range
-LlmCostTracker::LlmApiCall.between(1.week.ago, Time.current).cost_by_model
-```
-
-## Retention
-
-Retention is not enforced automatically. Use the rake task below if you need to delete older records in batches.
-
-```bash
-DAYS=90 bin/rails llm_cost_tracker:prune  # delete calls older than N days in batches
-```
-
-## Tag storage
-
-New installs use `jsonb` + GIN on PostgreSQL:
-
-```ruby
-t.jsonb :tags, null: false, default: {}
-add_index :llm_api_calls, :tags, using: :gin
 ```
 
-On other adapters tags fall back to JSON in a text column. `by_tag` uses JSONB containment on PG, text matching elsewhere.
-
-Upgrade an existing install:
+A text report is also one rake task away:
 
 ```bash
-bin/rails generate llm_cost_tracker:add_period_totals    # shared budget rollups
-bin/rails generate llm_cost_tracker:upgrade_tags_to_jsonb   # PG: text → jsonb + GIN
-bin/rails generate llm_cost_tracker:upgrade_cost_precision  # widen cost columns
-bin/rails generate llm_cost_tracker:add_latency_ms
-bin/rails db:migrate
+DAYS=7 bin/rails llm_cost_tracker:report
 ```
 
-On PostgreSQL, the generated `upgrade_tags_to_jsonb` migration rewrites `llm_api_calls`. Run it during a maintenance window on large tables, or replace it with a two-phase backfill for zero-downtime deploys.
+Full scope and helper reference: [`docs/querying.md`](docs/querying.md).
 
-## Mounting the dashboard
+## Dashboard
 
-Optional Rails Engine. Plain ERB, no JavaScript framework, no asset pipeline required. Requires Rails 7.1+; the core middleware works without Rails.
+Mount the engine wherever you want — it's plain ERB, no JavaScript bundle, no asset pipeline gymnastics:
 
 ```ruby
-# config/application.rb (or an initializer)
-require "llm_cost_tracker/engine"
-
 # config/routes.rb
 mount LlmCostTracker::Engine => "/llm-costs"
 ```
 
-Routes (GET-only; CSV export included):
-
-- `/llm-costs` — overview: spend with delta vs previous period, budget projection, spend anomaly banner, daily trend vs previous slice, provider rollup, top models
-- `/llm-costs/models` — by provider + model; sortable by spend, volume, avg cost, latency
-- `/llm-costs/calls` — filterable + paginated; outlier sort modes (expensive, largest input/output, slowest, unknown pricing); CSV export
-- `/llm-costs/calls/:id` — details with token mix and cost mix breakdowns
-- `/llm-costs/tags` — tag keys present in the dataset (PG/SQLite native; MySQL 8.0+ via JSON_TABLE)
-- `/llm-costs/tags/:key` — breakdown by values of a given tag key
-- `/llm-costs/data_quality` — unknown pricing share, untagged calls, missing latency
-
-No built-in auth is included. Tags carry whatever your app puts in them, so protect the mount point with your application's authentication.
-
-### Basic auth
-
-```ruby
-authenticated = ->(req) {
-  ActionController::HttpAuthentication::Basic.authenticate(req) do |name, password|
-    ActiveSupport::SecurityUtils.secure_compare(name, ENV.fetch("LLM_DASHBOARD_USER")) &
-      ActiveSupport::SecurityUtils.secure_compare(password, ENV.fetch("LLM_DASHBOARD_PASSWORD"))
-  end
-}
-constraints(authenticated) { mount LlmCostTracker::Engine => "/llm-costs" }
-```
-
-### Devise
-
-```ruby
-authenticate :user, ->(user) { user.admin? } do
-  mount LlmCostTracker::Engine => "/llm-costs"
-end
-```
-
-## ActiveSupport::Notifications
-
-```ruby
-ActiveSupport::Notifications.subscribe("llm_request.llm_cost_tracker") do |*, payload|
-  # payload =>
-  # {
-  #   provider: "openai", model: "gpt-4o",
-  #   input_tokens: 150, cache_read_input_tokens: 0, cache_write_input_tokens: 0,
-  #   hidden_output_tokens: 0, output_tokens: 42, total_tokens: 192, latency_ms: 248,
-  #   cost: {
-  #     input_cost: 0.000375, cache_read_input_cost: 0.0,
-  #     cache_write_input_cost: 0.0, output_cost: 0.00042,
-  #     total_cost: 0.000795, currency: "USD"
-  #   },
-  #   pricing_mode: "batch",
-  #   tags: { feature: "chat", user_id: 42 },
-  #   tracked_at: 2026-04-16 14:30:00 UTC
-  # }
-end
-```
-
-## Custom storage backend
-
-```ruby
-config.storage_backend = :custom
-config.custom_storage = ->(event) {
-  InfluxDB.write("llm_costs",
-    values: { cost: event.cost&.total_cost, tokens: event.total_tokens, latency_ms: event.latency_ms },
-    tags:   { provider: event.provider, model: event.model }
-  )
-}
-```
-
-## OpenAI-compatible providers
-
-```ruby
-config.openai_compatible_providers["gateway.example.com"] = "internal_gateway"
-```
-
-Configured hosts are parsed using the OpenAI-compatible usage shape (`prompt_tokens` / `completion_tokens` / `total_tokens`, `input_tokens` / `output_tokens`, and optional cached-input details). This covers OpenRouter, DeepSeek, and private gateways exposing Chat Completions / Responses / Completions / Embeddings.
+Pages: overview (spend trend, budget status, anomaly banner), models, calls (filterable, paginated, CSV export), tags, data quality. Reads `llm_api_calls`, so use `:active_record` storage if you want to mount it.
 
-## Custom parser
-
-For providers with a non-OpenAI usage shape:
-
-```ruby
-class AcmeParser < LlmCostTracker::Parsers::Base
-  HOSTS = %w[api.acme-llm.example].freeze
-  TRACKED_PATHS = %w[/v1/generate].freeze
-
-  def provider_names
-    %w[acme]
-  end
-
-  def match?(url)
-    match_uri?(url, hosts: HOSTS, exact_paths: TRACKED_PATHS)
-  end
-
-  def parse(_request_url, _request_body, response_status, response_body)
-    return nil unless response_status == 200
-
-    payload = safe_json_parse(response_body)
-    usage = payload.dig("usage")
-    return nil unless usage
-
-    LlmCostTracker::ParsedUsage.build(
-      provider: "acme",
-      model: payload["model"],
-      input_tokens: usage["input"] || 0,
-      output_tokens: usage["output"] || 0
-    )
-  end
-end
-
-LlmCostTracker::Parsers::Registry.register(AcmeParser)
-```
+Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs/dashboard.md).
 
 ## Supported providers
 
-| Provider | Auto-detected | Models with pricing |
+| Provider | Auto-detected | Coverage |
 |---|:---:|---|
-| OpenAI | ✅ | GPT-5.2/5.1/5, GPT-5 mini/nano, GPT-4.1, GPT-4o, o1/o3/o4-mini |
-| OpenRouter | ✅ | OpenAI-compatible usage; provider-prefixed OpenAI model IDs normalized when possible |
-| DeepSeek | ✅ | OpenAI-compatible usage; add `pricing_overrides` for DeepSeek models |
-| OpenAI-compatible hosts | 🔧 | Configure `openai_compatible_providers` |
-| Anthropic | ✅ | Claude Opus 4.6/4.1/4, Sonnet 4.6/4.5/4, Haiku 4.5, Claude 3.x |
-| Google Gemini | ✅ | Gemini 2.5 Pro/Flash/Flash-Lite, 2.0 Flash/Flash-Lite, 1.5 Pro/Flash |
-| Any other | 🔧 | Custom parser |
+| 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 |
+| Other OpenAI-compatible hosts | Configurable | Register the host via `config.openai_compatible_providers` |
+| Anything else | Configurable | Custom parser — see [`docs/extending.md`](docs/extending.md) |
 
-Endpoints: OpenAI Chat Completions / Responses / Completions / Embeddings; OpenAI-compatible equivalents; Anthropic Messages; Gemini `generateContent` and `streamGenerateContent`. All endpoints support streaming capture.
+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 whenever the provider emits final-usage events.
 
-## Safety
+## Privacy
 
-**By design, `llm_cost_tracker` never persists prompt or response content.** The only data stored per call is the metadata needed for a cost ledger (provider, model, token counts, cost, latency, tags, provider response ID, HTTP status, and a timestamp). Tags carry whatever your application passes in — treat them as user-controlled input and avoid putting request bodies, completions, or secrets into them.
+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.
 
-- No external HTTP calls at request-tracking time.
-- No prompt or response bodies stored.
-- Faraday responses not modified.
-- Authorization headers and API keys are never stored or logged.
-- Storage failures non-fatal by default (`storage_error_behavior = :warn`).
-- Budget and unknown-pricing errors are raised only when you opt in.
+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.
 
-## Thread safety (Puma, Sidekiq)
+## Documentation
 
-The gem is designed for multi-threaded hosts — Puma with `max_threads > 1` and Sidekiq with `concurrency > 1` are both supported. A few rules:
+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.
 
-- **Configure once at boot.** `LlmCostTracker.configure` deep-freezes `default_tags`, `pricing_overrides`, `report_tag_breakdowns`, and `openai_compatible_providers` when the block returns. Mutating or replacing shared fields through `LlmCostTracker.configuration` raises `FrozenError`.
-- **Use `:active_record` storage for shared ledgers.** Puma workers and Sidekiq processes do not share memory; `:log` and `:custom` backends see per-process state only. `:active_record` writes to a single table and is the right choice for dashboards and budget checks across processes.
-- **Size your connection pool.** Each tracked call on the middleware path issues up to three SQL queries (preflight `SUM`, `INSERT`, post-check `SUM`). Make sure the AR pool covers `puma max_threads + sidekiq concurrency` plus your app's own usage.
-- **Don't share a `StreamCollector` across threads you don't own.** The collector itself is thread-safe — `event`, `usage`, and `finish!` synchronize internally and `finish!` is idempotent — but the documented pattern is one collector per stream.
-- **`finish!` is a barrier.** Once a stream is finished, later `event`, `usage`, or `model=` calls raise `FrozenError` instead of mutating a closed collector.
-- **`ActiveSupport::Notifications` subscribers run synchronously** in the caller's thread. Keep them fast or hand off to a background job; otherwise they add latency to every tracked call.
-- **`storage_error_behavior = :raise` inside Sidekiq** will retry the job, which can duplicate an expensive LLM call. Prefer `:warn` plus a Notifications subscriber, or `:ignore`, for worker contexts.
+- [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)
+- [Extending](docs/extending.md)
+- [Production operations](docs/operations.md)
+- [Upgrading](docs/upgrading.md)
+- [Cookbook — per-client recipes](docs/cookbook.md)
+- [Architecture & design rules](docs/architecture.md)
 
 ## Known limitations
 
-- `:block_requests` is a best-effort guardrail, not a hard cap. Concurrent workers can pass preflight simultaneously and collectively overshoot the budget. Use an external quota system if you need a transactional cap.
-- Streaming capture relies on the provider emitting a final-usage event (OpenAI needs `stream_options: { include_usage: true }`); missing events are recorded with `usage_source: "unknown"` so they surface on the Data Quality page.
-- `provider_response_id` is stored only when the provider exposes a stable response object ID. Missing IDs stay `nil` and surface on the Data Quality page.
-- Cache write TTL variants (1h vs 5min writes) not modeled separately.
+- `:block_requests` is best-effort under concurrency, not a transactional cap.
+- Official SDK integrations cover non-streaming calls; streaming via the SDKs falls back to Faraday middleware or `track_stream`.
+- 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.
+- `provider_response_id` is stored only when the provider exposes a stable ID. Gemini is best-effort and varies by endpoint.
+- Cache write TTL variants on Anthropic (1h vs 5min writes) are not modeled separately yet.
 
 ## Development
 
-Architecture rules for future changes live in [`docs/architecture.md`](docs/architecture.md). Integration recipes live in [`docs/cookbook.md`](docs/cookbook.md).
-
 ```bash
 bundle install
-bundle exec rspec
-bundle exec rubocop
+bin/check       # rubocop + rspec
 ```
 
+Architecture rules and conventions for contributions live in [`AGENTS.md`](AGENTS.md) and [`docs/architecture.md`](docs/architecture.md).
+
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt).
+MIT — see [LICENSE.txt](LICENSE.txt).