Florian BRUNIAUX 76703ca3f5 feat: add comprehensive temporal audit system for token savings analytics ...

Implement day-by-day, week-by-week, and monthly breakdowns with JSON/CSV export
capabilities for in-depth token savings analysis and reporting.

New Features:
- Daily breakdown (--daily): Complete day-by-day statistics without 30-day limit
- Weekly breakdown (--weekly): Sunday-to-Saturday week aggregations with date ranges
- Monthly breakdown (--monthly): Calendar month aggregations (YYYY-MM format)
- Combined view (--all): All temporal breakdowns in single output
- JSON export (--format json): Structured data for APIs, dashboards, scripts
- CSV export (--format csv): Tabular data for Excel, Google Sheets, data science

Technical Implementation:
- src/tracking.rs: Add DayStats, WeekStats, MonthStats structures with Serialize
- src/tracking.rs: Implement get_all_days(), get_by_week(), get_by_month() SQL queries
- src/main.rs: Extend Commands::Gain with --daily, --weekly, --monthly, --all, --format flags
- src/gain.rs: Add print_daily_full(), print_weekly(), print_monthly() display functions
- src/gain.rs: Implement export_json() and export_csv() for data export

Documentation:
- docs/AUDIT_GUIDE.md: Comprehensive guide with examples, workflows, integrations
- README.md: Update Data section with new audit commands and export formats
- claudedocs/audit-feature-summary.md: Technical summary and implementation details

Database Scope:
- Global machine storage: ~/.local/share/rtk/history.db
- Shared across all projects, worktrees, and Claude sessions
- 90-day retention policy with automatic cleanup
- SQLite with indexed timestamp for fast aggregations

Use Cases:
- Trend analysis: identify daily/weekly patterns in token usage
- Cost reporting: monthly savings reports for budget tracking
- Data science: export CSV/JSON for pandas, R, Excel analysis
- Dashboards: integrate JSON export with Chart.js, D3.js, Grafana
- CI/CD: automated weekly/monthly savings reports via GitHub Actions

Examples:
  rtk gain --daily                    # Day-by-day breakdown
  rtk gain --weekly                   # Weekly aggregations
  rtk gain --all                      # All breakdowns combined
  rtk gain --all --format json | jq . # JSON export with jq
  rtk gain --all --format csv         # CSV for Excel/analysis

Backwards Compatibility:
- All existing flags (--graph, --history, --quota) preserved
- Default behavior unchanged (summary view)
- No database migration required
- Zero breaking changes

Performance:
- Efficient SQL aggregations with timestamp index
- No impact on rtk command execution speed
- Instant queries even with 90 days of data

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-30 11:12:45 +01:00

..

AUDIT_GUIDE.md

feat: add comprehensive temporal audit system for token savings analytics

2026-01-30 11:12:45 +01:00