feat(usage): add precise time ranges, offline reports, and GUI picker

docs-site/src/content/docs/fr/reference/cli/agents.md

@@ -90,7 +90,7 @@ Inspectez les requêtes de proxy, l’utilisation, le stockage, la mémoire et l
 | Alias ​​| Ressource équivalente |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json\|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today\|1d\|7d\|30d\|all>] [--surface <all\|codex\|claude\|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today\|yesterday\|1d\|7d\|30d\|all>] [--since <time>] [--until <time>] [--surface <all\|codex\|claude\|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table\|markdown\|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

docs-site/src/content/docs/ja/reference/cli/agents.md

@@ -61,7 +61,7 @@ ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5
 |別名 |同等のリソース |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today|yesterday|1d|7d|30d|all>] [--since <time>] [--until <time>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table|markdown|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

docs-site/src/content/docs/ko/reference/cli/agents.md

@@ -65,7 +65,7 @@ ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5
 | 별칭 | 대응 리소스 |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today|yesterday|1d|7d|30d|all>] [--since <time>] [--until <time>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table|markdown|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

docs-site/src/content/docs/reference/cli/agents.md

@@ -111,19 +111,26 @@ Inspect proxy requests, usage, storage, memory, and debug data. The direct alias
 | Alias | Equivalent resource |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today|yesterday|1d|7d|30d|all>] [--since <time>] [--until <time>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table|markdown|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 
 ```bash
 ocx observe usage --range 30d --json
 ```
 
-`--range today` (alias `1d`) reports the current local day. `--provider` and
+`--range today` (alias `1d`) reports the current local day, and `--range yesterday`
+reports the previous local day. `--since` and `--until` accept ISO-like local date/time
+values, epoch timestamps, or relative expressions such as `yesterday 09:17` and
+`today 04:23`. `--provider` and
 `--model` narrow the report to one upstream target — distinct from
 `--surface`, which selects the calling client (Codex, Claude Code, Grok)
 rather than the provider serving the request.
 
+`--offline` reads the bounded local usage ledger when the proxy is unavailable. It preserves
+time, surface, provider, and model filters. `--format markdown` emits a copy-ready report;
+`--format json` is equivalent to `--json`.
+
 The default view prints request, token and estimated-cost totals plus
 per-provider and per-model breakdowns. Costs are API list-price equivalents,
 not a billing receipt: subscription plans and provider credits are billed
@@ -132,6 +139,7 @@ separately, and requests with no matching price row are counted as
 
 ```bash
 ocx usage --range today --provider xai
+ocx usage --since "yesterday 09:17" --until "today 04:23" --format markdown
 ```
 
 ### `ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>`

docs-site/src/content/docs/reference/management-api.md

@@ -124,7 +124,7 @@ See [Combos](/guides/combos/) for target strategies, cooldowns, aliases, and rou
 | `GET /api/debug/usage-logs` | Read bounded usage-debug entries | — |
 | `GET /api/debug/injection-logs` | Read bounded guidance-injection debug entries | — |
 | `GET /api/claude/inbound-debug` | Read Claude inbound debug state and entries | — |
-| `GET /api/usage` | Summarize usage by range and client surface; Codex responses also include an `accounts` breakdown keyed by stable non-PII log labels | Returns an `error: "read_failed"` summary if storage cannot be read |
+| `GET /api/usage` | Summarize usage by preset range or inclusive `since`/`until` bounds and client surface; Codex responses also include an `accounts` breakdown keyed by stable non-PII log labels | 400 invalid time bound/order; returns an `error: "read_failed"` summary if storage cannot be read |
 | `GET /api/storage` | Scan Codex storage usage by bucket | Returns an `error: "scan_failed"` payload on scan failure |
 | `POST /api/storage/cleanup/preview` | Preview archived-session cleanup and return a binding digest | 400 `invalid_json` or `invalid_percent` |
 | `POST /api/storage/cleanup` | Quarantine or permanently remove the previewed archived set | 400 invalid input; 409 stale/busy/referenced state; 500 filesystem/database failure |
@@ -143,6 +143,12 @@ re-estimated from the pricing active when the summary is read. This is an API-eq
 not a subscription charge. New main-pool requests use the reserved `main` label; legacy bare
 `openai` rows remain in an ambiguous bucket instead of being reassigned from current configuration.
 
+Custom windows use `since` and/or `until`, for example
+`GET /api/usage?range=all&since=2026-08-29T09:17:00&until=2026-08-30T04:23:00`.
+Both bounds are inclusive and interpreted in the server's local time when no offset is supplied.
+Malformed bounds return `invalid_since` or `invalid_until`; reversed bounds return
+`invalid_time_range`. Custom summaries are never stored in the preset-range cache.
+
 :::caution
 Storage cleanup endpoints can move or permanently remove archived session data. Always preview
 first and submit the returned digest. Prefer quarantine when recovery may be needed.

docs-site/src/content/docs/ru/reference/cli/agents.md

@@ -71,7 +71,7 @@ ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5
 | Алиас | Эквивалентный ресурс |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today|yesterday|1d|7d|30d|all>] [--since <time>] [--until <time>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table|markdown|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

docs-site/src/content/docs/tr/reference/cli/agents.md

@@ -103,7 +103,7 @@ verilerini inceleyin. Doğrudan takma adlar şunlardır:
 | Takma ad | Eşdeğer kaynak |
 | --- | --- |
 | `ocx logs [filtreler] [--follow] [--json\|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today\|1d\|7d\|30d\|all>] [--surface <all\|codex\|claude\|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today\|yesterday\|1d\|7d\|30d\|all>] [--since <time>] [--until <time>] [--surface <all\|codex\|claude\|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table\|markdown\|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

docs-site/src/content/docs/zh-cn/reference/cli/agents.md

@@ -67,7 +67,7 @@ API key，且绝不会回退到 native alias。启用这组兼容选项前，请
 | 别名 | 对应资源 |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today|yesterday|1d|7d|30d|all>] [--since <time>] [--until <time>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table|markdown|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

docs-site/src/content/docs/zh-tw/reference/cli/agents.md

@@ -62,7 +62,7 @@ ocx route combo set reliable --targets ark/model-a:2,openai/gpt-5.5
 | 別名 | 等效資源 |
 | --- | --- |
 | `ocx logs [filters] [--follow] [--json|--jsonl]` | `ocx observe logs` |
-| `ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]` | `ocx observe usage` |
+| `ocx usage [--range <today|yesterday|1d|7d|30d|all>] [--since <time>] [--until <time>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--offline] [--format <table|markdown|json>] [--json]` | `ocx observe usage` |
 | `ocx storage [--json]` | `ocx observe storage` |
 | `ocx memory [--json]` | `ocx observe memory` |
 

gui/src/i18n/de.ts

@@ -794,6 +794,15 @@ export const de: Record<TKey, string> = {
   "usage.range.available": "Verfügbarer Verlauf",
   "usage.historyTruncated": "Die Summen beziehen sich nur auf den verfügbaren Verlauf, da ältere Nutzungsdaten nicht geladen wurden.",
   "usage.historyTruncatedWindow": "Die geladenen Zeilen haben Anfragestartzeiten zwischen {start} und {end}. Frühere Dateieinträge wurden durch das Leselimit ausgelassen, daher kann jeder gewählte Zeitraum unvollständig sein.",
+  "usage.range.today": "Heute",
+  "usage.range.yesterday": "Gestern",
+  "usage.range.custom": "Benutzerdefiniert...",
+  "usage.custom.since": "Von",
+  "usage.custom.until": "Bis",
+  "usage.custom.apply": "Anwenden",
+  "usage.custom.cancel": "Abbrechen",
+  "usage.custom.title": "Benutzerdefinierter Zeitraum",
+  "usage.custom.quick": "Schnellauswahl",
   "usage.range.30d": "30d",
   "usage.range.7d": "7d",
   "usage.card.requests": "Anfragen",

gui/src/i18n/en.ts

@@ -831,6 +831,15 @@ export const en = {
   "usage.range.available": "Available history",
   "usage.historyTruncated": "Totals cover available history only because older usage was not loaded.",
   "usage.historyTruncatedWindow": "Loaded rows have request start times ranging from {start} to {end}. Earlier file entries were omitted by the read limit, so any selected range may be incomplete.",
+  "usage.range.today": "Today",
+  "usage.range.yesterday": "Yesterday",
+  "usage.range.custom": "Custom...",
+  "usage.custom.since": "Since",
+  "usage.custom.until": "Until",
+  "usage.custom.apply": "Apply",
+  "usage.custom.cancel": "Cancel",
+  "usage.custom.title": "Custom time range",
+  "usage.custom.quick": "Quick date",
   "usage.range.30d": "30d",
   "usage.range.7d": "7d",
   "usage.card.requests": "Requests",

gui/src/i18n/fr.ts

@@ -808,6 +808,15 @@ export const fr: Record<TKey, string> = {
   "usage.range.available": "Historique disponible",
   "usage.historyTruncated": "Les totaux couvrent uniquement l’historique disponible, car les données d’utilisation plus anciennes n’ont pas été chargées.",
   "usage.historyTruncatedWindow": "Les heures de début des requêtes dans les lignes chargées vont de {start} à {end}. Les entrées antérieures du fichier ont été omises en raison de la limite de lecture ; toute période sélectionnée peut donc être incomplète.",
+  "usage.range.today": "Aujourd'hui",
+  "usage.range.yesterday": "Hier",
+  "usage.range.custom": "Personnalisé...",
+  "usage.custom.since": "Début",
+  "usage.custom.until": "Fin",
+  "usage.custom.apply": "Appliquer",
+  "usage.custom.cancel": "Annuler",
+  "usage.custom.title": "Période personnalisée",
+  "usage.custom.quick": "Date rapide",
   "usage.range.30d": "30 j",
   "usage.range.7d": "7 j",
   "usage.card.requests": "Requêtes",

gui/src/i18n/ja.ts

@@ -774,6 +774,15 @@ export const ja: Record<TKey, string> = {
   "usage.range.available": "利用可能な履歴",
   "usage.historyTruncated": "古い利用履歴が読み込まれていないため、合計は利用可能な履歴のみを対象とします。",
   "usage.historyTruncatedWindow": "読み込まれた行のリクエスト開始時刻は {start} から {end} の範囲です。読み取り上限によりファイル前方の記録が除外されているため、選択した期間は不完全な場合があります。",
+  "usage.range.today": "今日",
+  "usage.range.yesterday": "昨日",
+  "usage.range.custom": "カスタム...",
+  "usage.custom.since": "開始",
+  "usage.custom.until": "終了",
+  "usage.custom.apply": "適用",
+  "usage.custom.cancel": "キャンセル",
+  "usage.custom.title": "カスタム期間",
+  "usage.custom.quick": "クイック日付",
   "usage.range.30d": "30日",
   "usage.range.7d": "7日",
   "usage.card.requests": "リクエスト",

gui/src/i18n/ko.ts

@@ -816,6 +816,15 @@ export const ko: Record<TKey, string> = {
   "usage.range.available": "사용 가능한 기록",
   "usage.historyTruncated": "이전 사용 기록을 불러오지 않아 합계는 사용 가능한 기록만 포함합니다.",
   "usage.historyTruncatedWindow": "불러온 기록의 요청 시작 시각은 {start}부터 {end} 사이입니다. 읽기 한도 때문에 파일 앞부분의 기록이 빠졌으므로 선택한 기간이 완전하지 않을 수 있습니다.",
+  "usage.range.today": "오늘",
+  "usage.range.yesterday": "어제",
+  "usage.range.custom": "사용자 지정...",
+  "usage.custom.since": "시작",
+  "usage.custom.until": "종료",
+  "usage.custom.apply": "적용",
+  "usage.custom.cancel": "취소",
+  "usage.custom.title": "사용자 지정 기간",
+  "usage.custom.quick": "빠른 날짜",
   "usage.range.30d": "30일",
   "usage.range.7d": "7일",
   "usage.card.requests": "요청",

gui/src/i18n/ru.ts

@@ -815,6 +815,15 @@ export const ru: Record<TKey, string> = {
   "usage.range.available": "Доступная история",
   "usage.historyTruncated": "Итоги охватывают только доступную историю, поскольку старые данные не загружены.",
   "usage.historyTruncatedWindow": "У загруженных записей время начала запроса находится в диапазоне от {start} до {end}. Более ранние записи файла пропущены из-за лимита чтения, поэтому выбранный период может быть неполным.",
+  "usage.range.today": "Сегодня",
+  "usage.range.yesterday": "Вчера",
+  "usage.range.custom": "Настроить...",
+  "usage.custom.since": "Начало",
+  "usage.custom.until": "Конец",
+  "usage.custom.apply": "Применить",
+  "usage.custom.cancel": "Отмена",
+  "usage.custom.title": "Пользовательский период",
+  "usage.custom.quick": "Быстрая дата",
   "usage.range.30d": "30 дн.",
   "usage.range.7d": "7 дн.",
   "usage.card.requests": "Запросы",

gui/src/i18n/tr.ts

@@ -822,6 +822,15 @@ export const tr: Record<TKey, string> = {
   "usage.range.available": "Mevcut geçmiş",
   "usage.historyTruncated": "Toplamlar yalnızca mevcut geçmişi kapsar.",
   "usage.historyTruncatedWindow": "Yüklenen satırların istek başlangıç zamanları {start} ile {end} arasındadır. Dosyanın önceki kayıtları okuma sınırı nedeniyle atlandı, bu yüzden seçilen aralık eksik olabilir.",
+  "usage.range.today": "Bugün",
+  "usage.range.yesterday": "Dün",
+  "usage.range.custom": "Özel...",
+  "usage.custom.since": "Başlangıç",
+  "usage.custom.until": "Bitiş",
+  "usage.custom.apply": "Uygula",
+  "usage.custom.cancel": "İptal",
+  "usage.custom.title": "Özel zaman aralığı",
+  "usage.custom.quick": "Hızlı tarih",
   "usage.range.30d": "30 gün",
   "usage.range.7d": "7 gün",
   "usage.card.requests": "İstekler",

gui/src/i18n/zh-TW.ts

@@ -641,6 +641,15 @@ export const zhTW: Record<TKey, string> = {
   "usage.empty": "尚無用量紀錄。透過代理傳送請求後將在此顯示。",
   "usage.loadError": "無法載入用量資料。",
   "usage.range.all": "全部",
+  "usage.range.today": "今天",
+  "usage.range.yesterday": "昨天",
+  "usage.range.custom": "自訂...",
+  "usage.custom.since": "起始時間",
+  "usage.custom.until": "截止時間",
+  "usage.custom.apply": "篩選",
+  "usage.custom.cancel": "取消",
+  "usage.custom.title": "自訂時間範圍",
+  "usage.custom.quick": "快速日期",
   "usage.range.30d": "30 天",
   "usage.range.7d": "7 天",
   "usage.card.requests": "請求數",

gui/src/i18n/zh.ts

@@ -809,6 +809,15 @@ export const zh: Record<TKey, string> = {
   "usage.range.available": "可用历史",
   "usage.historyTruncated": "由于未加载较早的使用记录，合计仅涵盖可用历史。",
   "usage.historyTruncatedWindow": "已加载记录的请求开始时间介于 {start} 到 {end} 之间。受读取上限限制，文件较前的条目已被省略，所选时间范围可能不完整。",
+  "usage.range.today": "今天",
+  "usage.range.yesterday": "昨天",
+  "usage.range.custom": "自定义...",
+  "usage.custom.since": "起始时间",
+  "usage.custom.until": "截止时间",
+  "usage.custom.apply": "筛选",
+  "usage.custom.cancel": "取消",
+  "usage.custom.title": "自定义时间范围",
+  "usage.custom.quick": "快捷日期",
   "usage.range.30d": "30 天",
   "usage.range.7d": "7 天",
   "usage.card.requests": "请求数",