eurysx 0.1.0__tar.gz

eurysx-0.1.0/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+## [0.1.0] - Local observability, diagnostics, pacing, and stable exports
+
+### Fixed
+
+- Parse Claude Code date-only timestamps correctly; aggregate rates use observed dates and omit false daily spikes.
+- Attribute Pi sessions from session headers, retaining the legacy per-event fallback.
+- Calculate pacing from the full calendar budget window; provider budgets override agent budgets for their routes.
+
+### Added
+
+- Activity ratios for requests/turns/tool calls, reported as `N/A` when their inputs are absent.
+- Read-only parser-drift and unreachable-source warnings; retained history is never deleted.
+- `eurysx doctor` for terminal-only harness, source, pricing-cache, and configuration diagnostics. Failed-refresh report warnings are agent-scoped.
+- Preference budgets, deterministic pacing, and exact unresolved-route diagnostics; subscription billing remains `N/A`.
+- Stable JSON schema v1 plus CSV and Markdown exports from the shared analysis result.
+- Operational manual with CLI/output redirects and a source-drift regression check.
+- Trusted-Publishing GitHub workflow: validation, PyPI upload, and changelog-based GitHub Release.
+
+### Tests
+
+- Coverage for timestamp scope, Pi attribution, ratios, diagnostics, stored-source failures, and the doctor command.
+
+## [0.0.5] - More hardening: pushdown, selectors, grouping, comparisons
+
+### Added
+
+- `--model` and `--provider` selectors, SQL WHERE filters in `store.events()`,
+  combinable with `--agent` and the period selectors; NULL providers match
+  `--provider unknown` (COALESCE).
+- `--billing-mode` (metered|subscription|credit|quota|local|unknown), applied
+  post-pricing via the `analyze_agent(billing_modes=...)` hook: billing_mode
+  is a pricing-time artifact flipped to `metered` on recorded-cost conflict,
+  so SQL cannot pre-filter it.
+- `period_comparison`: bounded runs compare the current period against the
+  same-length previous window (`_previous_window`, same filters) — terminal
+  `PERIOD COMPARISON` (tokens, cost, entries, requests + Δ) and an additive
+  JSON block; all-time runs omit it.
+
+### Changed
+
+- OpenCode timestamps stored as ISO-8601 (parser v3); epoch-millis rows
+  re-collect on refresh.
+- Claude Code aggregate scope warning now via a store presence check, so it
+  survives SQL filtering.
+- `store.events()` filters agents, dates, models, and providers in SQL; the
+  Python date filter remains as the equivalence reference.
+- Indices on provider, model, project, session (additive, idempotent).
+- `AgentStats` gained `project_breakdown`/`session_breakdown` (model_breakdown
+  shape; `unknown` bucket for unattributed rows), shown in terminal as
+  `BREAKDOWN BY SESSION`/`BREAKDOWN BY PROJECT` and in JSON; unattributed-only
+  sections print `No ... attribution available.`.
+
+### Tests
+
+- SQL-vs-Python equivalence, presence check, indices, grouping (incl.
+  unattributed), two-period reuse/disjointness.
+- Per-selector and combination tests incl.
+  recorded-cost-flips-to-metered; previous-window math; simulated-CLI
+  comparison asserting values and delta.
+- Phase 1 baseline extended for additive keys `project_breakdown`,
+  `session_breakdown`, `period_comparison`; Phase 6 pins the final contract.
+
+## [0.0.4] - Report baseline + result seams
+
+### Added
+
+- Tests lock JSON `--output` schema and terminal report key sections against a hermetic fixture to assert exact values.
+- Added cache read and cache efficiency ratios to JSON exports (previously terminal-only).
+- `AnalysisReport` encapsulates period, per-agent stats/display periods, and pricing/preferences provenance; moved JSON assembly from CLI to `render.py`.
+- `UsageAnalyzer.display_period` unit tests for ranged and all-time period derivations.
+
+### Changed
+
+- Terminal report, comparison summary, and JSON export now consume `AnalysisReport` instead of CLI-assembled payloads.
+- Internal test-only models moved out of CLI exports; tests now import `eurysx.models` directly.
+
+## [0.0.3] - Incremental collection + attribution and diagnostics
+
+### Added
+
+- Incremental per-source collection: collectors enumerate raw sources with stat
+  fingerprints and a parser version; the CLI skips unchanged sources and
+  transactionally replaces only sources that moved.
+- Best-effort project attribution: Pi session-header `cwd`, Codex
+  `session_meta.cwd`, and OpenCode's `session.directory` (when present) are
+  stored per event as `project_id`; Claude Code aggregate rows stay unattributed.
+- Failed source refreshes keep their last good events, record the error on the
+  source row, and `report` warns when last-good data is being shown.
+
+### Changed
+
+- Default and `report` commands both read usage back from the store after
+  collection; legacy per-agent bulk `collector:<agent>` store rows are purged.
+- Collectors propagate read errors instead of printing and returning partial
+  data. Pi, Codex, and OpenCode parser versions moved to 2.
+
+## [0.0.2] - Local store implementation + module restructure
+
+### Added
+
+- Local SQLite usage storage with decimal-text recorded costs.
+- `eurysx collect` and `eurysx report` workflows; stored reports do not collect
+  agent history.
+
+### Changed
+
+- Source layout now uses the `src/eurysx` package
+- CLI orchestration now delegates to focused collector, pricing, analysis, and rendering modules.
+
+## [0.0.1] - Core CLI baseline
+
+### Added
+
+- `eurysx` CLI for Claude Code, OpenCode, Pi, and Codex local usage data.
+- Token, request, turn, tool-call, model, provider, session, and pricing-source reporting.
+- JSON reports, `--version`/`-v`, and explicit rolling, calendar, and ISO date selectors.
+- Checkout-local pricing config/cache paths with explicit environment overrides.
+- Configurable pricing resolution: recorded cost, overrides, enabled sources, cache fallback, then unknown.
+- User-owned per-agent route and billing preferences with pricing-provider mapping.
+- Ordered provider-aware pricing source fallbacks and a project-local cache.
+- Sanitized collector fixtures, pricing regression tests, setuptools metadata, and MIT license.
+
+### Changed
+
+- Reports label money as known cost and expose unknown-cost tokens and priced-token coverage.
+- Selected date ranges exclude `Claude Code`'s aggregate stats-cache data and emit a scope warning.
+- Source distributions include the changelog and safe pricing configuration sample.
+- Empty-token coverage is `N/A`; malformed pricing configuration is reported as a diagnostic.
+- `OpenCode` turn detection no longer depends on SQLite message-row order.
+- All-time reports derive cost-rate periods from observed usage dates.
+- Reports separate metered token coverage from subscription, credit, quota, local, and unknown usage.
+- Codex preserves recorded route-provider metadata; provider-qualified prices no longer cross-match.
+- Preferences now use agent defaults and provider overrides; `aws-bedrock` is
+  renamed to `amazon-bedrock` in pricing configuration and cache provenance.
+- Configuration documentation and samples now distinguish required enabled-source
+  settings from optional agent and provider policies.
+- OpenCode collector parity now uses a tracked, sanitized SQL fixture that builds
+  its temporary SQLite database during tests.

eurysx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openlines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eurysx-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+include config/pricing.jsonc.sample
+include config/preferences.jsonc.sample

eurysx-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: eurysx
+Version: 0.1.0
+Summary: Local usage intelligence for AI coding agents
+Author: openlines
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Eurysx
+
+Local-first usage observability for Claude Code, OpenCode, Pi, and Codex.
+
+Eurysx reads local agent history and reports tokens, requests, turns, tool calls,
+estimated or recorded cost, and pricing provenance. It does not upload usage data
+or persist prompts, responses, file contents, tool arguments, or tool results.
+
+> Eurysx v0.1.0 is a local CLI, not a hosted service.
+
+## Install
+
+```bash
+python3 -m pip install .
+eurysx --help
+```
+
+## Run
+
+```bash
+eurysx --version
+eurysx
+eurysx --agent codex --days 30
+eurysx --agent all --month 2026-08
+eurysx --agent pi --from 2026-08-01 --to 2026-08-15
+eurysx --agent all --days 30 --output reports/usage.json
+eurysx --refresh-pricing
+eurysx collect --agent codex
+eurysx report --agent codex --days 30
+eurysx doctor
+```
+
+`reports/` is ignored by Git.
+
+`eurysx` collects current local metadata and then reports it. `collect` stores
+metadata only; `report` reads the local store without collecting. `doctor` is
+terminal-only and reports local harness, source, pricing-cache, and configuration
+health without parsing history, refreshing prices, or deleting retained data. During Act II,
+the store is `data/eurysx.db` relative to the current project directory. Set
+`EURYSX_DATA_DIR` only to deliberately relocate it.
+
+Period selectors are mutually exclusive: `--days N`, `--weeks N`,
+`--from YYYY-MM-DD [--to YYYY-MM-DD]`, `--month YYYY-MM`,
+`--quarter YYYY-QN`, `--year YYYY`, and `--ytd`. Rolling periods include today.
+
+Filter selectors `--model`, `--provider`, and `--billing-mode` narrow the
+analyzed rows and combine with `--agent` and the period selectors; bounded
+period runs also compare against the same-length previous window. See the
+[operational manual](docs/manual.md) for details.
+
+## Documentation
+
+The [operational manual](docs/manual.md) is the authoritative command, output,
+configuration, and diagnostics reference. Legacy [CLI](docs/cli.md) and
+[output](docs/output.md) pages redirect there.
+
+This manual is the authoritative contract for the JSONC configuration files.
+
+## Configuration manual
+
+Eurysx is checkout-local during Act I. It reads and writes only these paths by
+default, relative to the directory where you run `eurysx`:
+
+```text
+eurysx/
+├── config/pricing.jsonc
+├── config/preferences.jsonc
+└── cache/
+```
+
+It does not use `~/Library/Application Support`, XDG directories, or other
+system-level application folders. The local configuration and cache are ignored
+by Git. Create them from the tracked templates:
+
+```bash
+cp config/pricing.jsonc.sample config/pricing.jsonc
+cp config/preferences.jsonc.sample config/preferences.jsonc
+```
+
+Both files are JSONC: comments and trailing commas are allowed. Both are
+optional. Without them, Eurysx retains recorded usage and marks unresolved cost
+as unknown. Use `EURYSX_CONFIG_DIR` and `EURYSX_CACHE_DIR` only when deliberately
+relocating those two directories, for example to a removable development volume.
+
+### `preferences.jsonc`: agent and provider policy
+
+`preferences.jsonc` declares a schema version 2 policy. An agent-level policy
+applies to every model when the collector has no provider metadata. `providers`
+overrides that policy only for an exact recorded provider. There are no
+model-match rules.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "agents": {
+    "claude-code": {
+      "provider": "amazon-bedrock",
+      "billingMode": "metered",
+      "pricing": {
+        "source": "amazon-bedrock",
+        "otherSources": ["models-dev", "pi-models-store"]
+      }
+    },
+    "codex": {
+      "providers": {
+        "openai": { "billingMode": "subscription" },
+        "amazon-bedrock": {
+          "billingMode": "metered",
+          "pricing": { "source": "amazon-bedrock", "otherSources": ["models-dev"] }
+        },
+        "litellm": { "billingMode": "local" }
+      }
+    }
+  }
+}
+```
+
+`schemaVersion` and `agents` are the expected top-level fields. `schemaVersion`
+is currently informational; Eurysx does not reject the file based on its value.
+The file itself and each agent entry are optional. Omit an agent entry when you
+want its usage to remain unclassified. Supported agent keys are `claude-code`,
+`codex`, `opencode`, and `pi`; unknown keys are ignored.
+
+| Policy field | Required? | Meaning |
+| --- | --- | --- |
+| `provider` | Optional | Effective provider when the collector does not record one. Usually needed for an agent-level metered policy. |
+| `billingMode` | Optional | `metered`, `subscription`, `credit`, `quota`, `local`, or `unknown`. Omit it to let a matching provider policy decide; if no policy supplies it, Eurysx uses `unknown`. |
+| `providers` | Optional | Map of exact recorded provider names to policy objects. Provider-policy fields override the agent-level fields. |
+| `pricing` | Optional | Pricing lookup policy. For a config-priced metered route, include at least one valid `source` or `otherSources` entry. |
+| `pricing.source` | Optional | Primary enabled source name from `pricing.jsonc`. |
+| `pricing.otherSources` | Optional | Ordered enabled fallback source names from `pricing.jsonc`. |
+
+`subscription`, `credit`, `quota`, and `local` report `N/A` incremental USD.
+`metered` resolves pricing. A source name that is missing, disabled, or lacks an
+exact provider/model price is skipped. Recorded harness cost always wins.
+
+For an agent using more than one provider, omit agent-level `billingMode` rather
+than setting it to `unknown` or an empty value. JSON has no useful blank value
+here: `"billingMode": ""` is invalid policy data and is reported as unknown.
+For example, Codex can classify its recorded OpenAI route as `subscription`, its
+recorded Bedrock route as `metered`, and its recorded LiteLLM route as `local`.
+If a record has no provider, or its provider is absent from `providers`, its
+billing mode is `unknown` unless the agent-level policy defines one. Optional
+budgets use `{"usd": 100, "period": "month"}` under an agent or exact provider;
+invalid budgets disable pacing with a warning.
+
+Billing modes describe incremental cost, not capability:
+
+| Mode | Eurysx cost treatment |
+| --- | --- |
+| `metered` | Resolves per-token USD pricing. |
+| `subscription`, `credit`, `quota`, `local` | Reports `N/A` incremental USD. Eurysx does not allocate fees or convert credits. |
+| `unknown` | Retains usage and reports cost as unknown until you classify it or add pricing. |
+
+Recorded harness cost always wins. If a recorded cost conflicts with a
+non-metered policy, Eurysx keeps the recorded cost and warns.
+
+### `pricing.jsonc`: price sources and manual overrides
+
+`pricing.jsonc` supplies per-million-token USD prices only for `metered` usage.
+It has `sources`, provider-scoped `aliases`, and `overrides`. The file is
+optional. Configure an enabled source before naming it in `pricing.source` or
+`pricing.otherSources`.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "sources": {
+    "amazon-bedrock": {
+      "enabled": true,
+      "profile": "your-aws-profile",
+      "region": "ap-southeast-1",
+      "refreshDays": 7
+    }
+  },
+  "aliases": {
+    "amazon-bedrock": {
+      "claude-sonnet-4-6": "global.anthropic.claude-sonnet-4-6"
+    }
+  },
+  "overrides": {
+    "amazon-bedrock/bedrock.gpt-5.6": {
+      "input": 0,
+      "output": 0,
+      "cacheRead": 0,
+      "cacheWrite": 0
+    }
+  }
+}
+```
+
+Supported sources are:
+
+| Source | Required when enabled | Optional | Reads from |
+| --- | --- | --- | --- |
+| `amazon-bedrock` | `enabled: true`, `profile`, `region` | `refreshDays` | `aws pricing get-products` for Amazon Bedrock. |
+| `pi-models-store` | `enabled: true` | `refreshDays` | `~/.pi/agent/models-store.json`. |
+| `models-dev` | `enabled: true`, `url` | `refreshDays` | The configured models.dev-compatible URL. |
+
+Aliases map collector model names to a source's canonical model ID without
+changing billing policy. Override keys are `provider/model`; values are USD per
+one million tokens. An override requires `input` and `output`; `cacheRead` and
+`cacheWrite` are optional and default to zero. Never use a bare model override
+to price multiple providers.
+
+Resolution order is: recorded cost, explicit override, the route primary source,
+the route's `otherSources` in order, then unknown. Eurysx never guesses a number
+for an unpriced model.
+
+### Refreshing and inspecting pricing
+
+Eurysx creates `cache/` in the current project directory on every run. Enabled
+sources cache normalized results in `cache/pricing-<source>.json`. Use the
+normal command to use a fresh cache, or force a refresh:
+
+```bash
+eurysx --refresh-pricing
+```
+
+If refresh fails, Eurysx uses a valid existing cache and reports a warning. If
+no valid price is available, the associated metered usage remains unknown rather
+than being reported as free. The cache contains pricing metadata, not prompts or
+credentials. Do not add API keys or LiteLLM master keys to either configuration
+file.
+
+## Current limits
+
+- Claude Code's stats cache is aggregate-only. Eurysx excludes it from selected
+  date ranges and reports a scope warning; it remains available for all-time use.
+  Its single row per model is stamped with `lastComputedDate`, so all-time Claude
+  Code rates spread the whole aggregate over that observed span and its
+  day-by-day activity table stays empty (`n/a` per-active-day lines) rather than
+  inventing a one-day spike.
+- The supported collectors are Claude Code, OpenCode, Pi, and Codex only.
+- Pricing data is metadata only. Source pricing may be unavailable, in which case
+  the relevant cost remains unknown.
+- Preferences use recorded route metadata or exact user rules. Eurysx does not
+  call LiteLLM or provider APIs for route discovery and never reads credentials.
+- A report with usage entries but no tokens displays priced-token coverage as
+  `N/A`.
+- Collector fixtures verify known file shapes, not every live harness release.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest -v tests/test_eurysx.py
+python3 -m py_compile src/eurysx/*.py
+```
+
+Sanitized collector fixtures cover Claude Code, Codex, Pi, and OpenCode. The
+OpenCode SQL fixture builds a temporary SQLite database during the test rather
+than committing a binary database file.

eurysx-0.1.0/README.md

@@ -0,0 +1,252 @@
+# Eurysx
+
+Local-first usage observability for Claude Code, OpenCode, Pi, and Codex.
+
+Eurysx reads local agent history and reports tokens, requests, turns, tool calls,
+estimated or recorded cost, and pricing provenance. It does not upload usage data
+or persist prompts, responses, file contents, tool arguments, or tool results.
+
+> Eurysx v0.1.0 is a local CLI, not a hosted service.
+
+## Install
+
+```bash
+python3 -m pip install .
+eurysx --help
+```
+
+## Run
+
+```bash
+eurysx --version
+eurysx
+eurysx --agent codex --days 30
+eurysx --agent all --month 2026-08
+eurysx --agent pi --from 2026-08-01 --to 2026-08-15
+eurysx --agent all --days 30 --output reports/usage.json
+eurysx --refresh-pricing
+eurysx collect --agent codex
+eurysx report --agent codex --days 30
+eurysx doctor
+```
+
+`reports/` is ignored by Git.
+
+`eurysx` collects current local metadata and then reports it. `collect` stores
+metadata only; `report` reads the local store without collecting. `doctor` is
+terminal-only and reports local harness, source, pricing-cache, and configuration
+health without parsing history, refreshing prices, or deleting retained data. During Act II,
+the store is `data/eurysx.db` relative to the current project directory. Set
+`EURYSX_DATA_DIR` only to deliberately relocate it.
+
+Period selectors are mutually exclusive: `--days N`, `--weeks N`,
+`--from YYYY-MM-DD [--to YYYY-MM-DD]`, `--month YYYY-MM`,
+`--quarter YYYY-QN`, `--year YYYY`, and `--ytd`. Rolling periods include today.
+
+Filter selectors `--model`, `--provider`, and `--billing-mode` narrow the
+analyzed rows and combine with `--agent` and the period selectors; bounded
+period runs also compare against the same-length previous window. See the
+[operational manual](docs/manual.md) for details.
+
+## Documentation
+
+The [operational manual](docs/manual.md) is the authoritative command, output,
+configuration, and diagnostics reference. Legacy [CLI](docs/cli.md) and
+[output](docs/output.md) pages redirect there.
+
+This manual is the authoritative contract for the JSONC configuration files.
+
+## Configuration manual
+
+Eurysx is checkout-local during Act I. It reads and writes only these paths by
+default, relative to the directory where you run `eurysx`:
+
+```text
+eurysx/
+├── config/pricing.jsonc
+├── config/preferences.jsonc
+└── cache/
+```
+
+It does not use `~/Library/Application Support`, XDG directories, or other
+system-level application folders. The local configuration and cache are ignored
+by Git. Create them from the tracked templates:
+
+```bash
+cp config/pricing.jsonc.sample config/pricing.jsonc
+cp config/preferences.jsonc.sample config/preferences.jsonc
+```
+
+Both files are JSONC: comments and trailing commas are allowed. Both are
+optional. Without them, Eurysx retains recorded usage and marks unresolved cost
+as unknown. Use `EURYSX_CONFIG_DIR` and `EURYSX_CACHE_DIR` only when deliberately
+relocating those two directories, for example to a removable development volume.
+
+### `preferences.jsonc`: agent and provider policy
+
+`preferences.jsonc` declares a schema version 2 policy. An agent-level policy
+applies to every model when the collector has no provider metadata. `providers`
+overrides that policy only for an exact recorded provider. There are no
+model-match rules.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "agents": {
+    "claude-code": {
+      "provider": "amazon-bedrock",
+      "billingMode": "metered",
+      "pricing": {
+        "source": "amazon-bedrock",
+        "otherSources": ["models-dev", "pi-models-store"]
+      }
+    },
+    "codex": {
+      "providers": {
+        "openai": { "billingMode": "subscription" },
+        "amazon-bedrock": {
+          "billingMode": "metered",
+          "pricing": { "source": "amazon-bedrock", "otherSources": ["models-dev"] }
+        },
+        "litellm": { "billingMode": "local" }
+      }
+    }
+  }
+}
+```
+
+`schemaVersion` and `agents` are the expected top-level fields. `schemaVersion`
+is currently informational; Eurysx does not reject the file based on its value.
+The file itself and each agent entry are optional. Omit an agent entry when you
+want its usage to remain unclassified. Supported agent keys are `claude-code`,
+`codex`, `opencode`, and `pi`; unknown keys are ignored.
+
+| Policy field | Required? | Meaning |
+| --- | --- | --- |
+| `provider` | Optional | Effective provider when the collector does not record one. Usually needed for an agent-level metered policy. |
+| `billingMode` | Optional | `metered`, `subscription`, `credit`, `quota`, `local`, or `unknown`. Omit it to let a matching provider policy decide; if no policy supplies it, Eurysx uses `unknown`. |
+| `providers` | Optional | Map of exact recorded provider names to policy objects. Provider-policy fields override the agent-level fields. |
+| `pricing` | Optional | Pricing lookup policy. For a config-priced metered route, include at least one valid `source` or `otherSources` entry. |
+| `pricing.source` | Optional | Primary enabled source name from `pricing.jsonc`. |
+| `pricing.otherSources` | Optional | Ordered enabled fallback source names from `pricing.jsonc`. |
+
+`subscription`, `credit`, `quota`, and `local` report `N/A` incremental USD.
+`metered` resolves pricing. A source name that is missing, disabled, or lacks an
+exact provider/model price is skipped. Recorded harness cost always wins.
+
+For an agent using more than one provider, omit agent-level `billingMode` rather
+than setting it to `unknown` or an empty value. JSON has no useful blank value
+here: `"billingMode": ""` is invalid policy data and is reported as unknown.
+For example, Codex can classify its recorded OpenAI route as `subscription`, its
+recorded Bedrock route as `metered`, and its recorded LiteLLM route as `local`.
+If a record has no provider, or its provider is absent from `providers`, its
+billing mode is `unknown` unless the agent-level policy defines one. Optional
+budgets use `{"usd": 100, "period": "month"}` under an agent or exact provider;
+invalid budgets disable pacing with a warning.
+
+Billing modes describe incremental cost, not capability:
+
+| Mode | Eurysx cost treatment |
+| --- | --- |
+| `metered` | Resolves per-token USD pricing. |
+| `subscription`, `credit`, `quota`, `local` | Reports `N/A` incremental USD. Eurysx does not allocate fees or convert credits. |
+| `unknown` | Retains usage and reports cost as unknown until you classify it or add pricing. |
+
+Recorded harness cost always wins. If a recorded cost conflicts with a
+non-metered policy, Eurysx keeps the recorded cost and warns.
+
+### `pricing.jsonc`: price sources and manual overrides
+
+`pricing.jsonc` supplies per-million-token USD prices only for `metered` usage.
+It has `sources`, provider-scoped `aliases`, and `overrides`. The file is
+optional. Configure an enabled source before naming it in `pricing.source` or
+`pricing.otherSources`.
+
+```jsonc
+{
+  "schemaVersion": 2,
+  "sources": {
+    "amazon-bedrock": {
+      "enabled": true,
+      "profile": "your-aws-profile",
+      "region": "ap-southeast-1",
+      "refreshDays": 7
+    }
+  },
+  "aliases": {
+    "amazon-bedrock": {
+      "claude-sonnet-4-6": "global.anthropic.claude-sonnet-4-6"
+    }
+  },
+  "overrides": {
+    "amazon-bedrock/bedrock.gpt-5.6": {
+      "input": 0,
+      "output": 0,
+      "cacheRead": 0,
+      "cacheWrite": 0
+    }
+  }
+}
+```
+
+Supported sources are:
+
+| Source | Required when enabled | Optional | Reads from |
+| --- | --- | --- | --- |
+| `amazon-bedrock` | `enabled: true`, `profile`, `region` | `refreshDays` | `aws pricing get-products` for Amazon Bedrock. |
+| `pi-models-store` | `enabled: true` | `refreshDays` | `~/.pi/agent/models-store.json`. |
+| `models-dev` | `enabled: true`, `url` | `refreshDays` | The configured models.dev-compatible URL. |
+
+Aliases map collector model names to a source's canonical model ID without
+changing billing policy. Override keys are `provider/model`; values are USD per
+one million tokens. An override requires `input` and `output`; `cacheRead` and
+`cacheWrite` are optional and default to zero. Never use a bare model override
+to price multiple providers.
+
+Resolution order is: recorded cost, explicit override, the route primary source,
+the route's `otherSources` in order, then unknown. Eurysx never guesses a number
+for an unpriced model.
+
+### Refreshing and inspecting pricing
+
+Eurysx creates `cache/` in the current project directory on every run. Enabled
+sources cache normalized results in `cache/pricing-<source>.json`. Use the
+normal command to use a fresh cache, or force a refresh:
+
+```bash
+eurysx --refresh-pricing
+```
+
+If refresh fails, Eurysx uses a valid existing cache and reports a warning. If
+no valid price is available, the associated metered usage remains unknown rather
+than being reported as free. The cache contains pricing metadata, not prompts or
+credentials. Do not add API keys or LiteLLM master keys to either configuration
+file.
+
+## Current limits
+
+- Claude Code's stats cache is aggregate-only. Eurysx excludes it from selected
+  date ranges and reports a scope warning; it remains available for all-time use.
+  Its single row per model is stamped with `lastComputedDate`, so all-time Claude
+  Code rates spread the whole aggregate over that observed span and its
+  day-by-day activity table stays empty (`n/a` per-active-day lines) rather than
+  inventing a one-day spike.
+- The supported collectors are Claude Code, OpenCode, Pi, and Codex only.
+- Pricing data is metadata only. Source pricing may be unavailable, in which case
+  the relevant cost remains unknown.
+- Preferences use recorded route metadata or exact user rules. Eurysx does not
+  call LiteLLM or provider APIs for route discovery and never reads credentials.
+- A report with usage entries but no tokens displays priced-token coverage as
+  `N/A`.
+- Collector fixtures verify known file shapes, not every live harness release.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest -v tests/test_eurysx.py
+python3 -m py_compile src/eurysx/*.py
+```
+
+Sanitized collector fixtures cover Claude Code, Codex, Pi, and OpenCode. The
+OpenCode SQL fixture builds a temporary SQLite database during the test rather
+than committing a binary database file.