Add ReportSAFE

A macOS menu bar application that monitors AI coding assistant usage quotas. Keep track of your Claude, Codex, Antigravity ,and Gemini usage at a glance.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: add-report
description: >
  Guide for adding new report cards to ClaudeBar that analyze local data sources and display
  metrics with comparison deltas. Use this skill when:
  (1) Adding a new report/analytics card (e.g., weekly summary, model breakdown, session stats)
  (2) Showing usage history in a new way, or reading another tool's usage logs
  (3) Adding comparison cards that show "today vs previous" style deltas
  (4) Building any feature that follows the DailyUsage pattern (days → report value → card)
---

# Add Report Card to ClaudeBar

Add report cards that turn a login's usage history into metrics with comparison
deltas, shown in the existing card style, test first.

## When to Use

This skill covers **report-style features** — cards that:
- Aggregate a login's days of usage (cost, tokens, time, sessions)
- Compare periods (today vs yesterday, this week vs last week)
- Read another tool's usage logs (as data in its definition)
- Display results in cards matching the existing UI

## First, which kind of report is it?

Usage history is data now ([daily-usage design](../../../docs/features/daily-usage/design.md)).
A report is almost always a new **view over days the login already reads**, not new
reading code. Place it before anything else:

| The person wants... | It is | You write |
|---|---|---|
| a new look at usage this app already reads — this week vs last, cost per model, a 30-day chart | a **report over days**: the page asks `account.usageHistory?.days(in: range)` and a value in `Quotas` turns the days into the report | a `Quotas` value + its tests, a card. **No reading code** |
| the same history for another tool (its own log files) | a **`usageHistory` block** in that provider's definition | JSON (paths, `where`, fields, `prices`), its golden tests — no Swift |
| history from a log format no reader understands yet | a **new reader**, named for the format, in `Modules/DataSources/Sources/Internal/Logs/` | the reader, test-first in `DataSourcesTests`, then the JSON; a row in ENGINE_DESIGN §1 |
| an answer to a different question than "how much did I use?" | a **capability** (CANONICAL §2.1): declared in the definition, a handle on `Account` that is `nil` when not declared | design first; a runner outside the modules is supplied by the `Engine` (TARGET_ARCHITECTURE §10) |

**Never:** a field on `UsageSnapshot` (the kernel is shrinking toward `Usage`,
[CANONICAL_MODEL §6](../../../docs/architecture/CANONICAL_MODEL.md#6--what-is-deliberately-not-in-the-tree)),
an `XxxAnalyzer` / `XxxAnalyzing` protocol, a parser in `Sources/Infrastructure`, or a
vendor-named type in a module.

> **Reference implementation:** `references/daily-usage-pattern.md` — *TODAY'S USAGE*:
> Claude's logs and prices as data, `UsageLog` in DataSources, `account.usageHistory`,
> `DailyUsageReport` in Quotas, `DailyUsageCardView`. The Leaderboard reads 30 days the
> same way (`login.history.days(in:)` → `DailyTokens.summed`).

> **Check the design first** — the docs are the source of truth ([AGENTS.md](../../../AGENTS.md#design-docs-are-the-source-of-truth)):
> USER_JOURNEYS, CANONICAL_MODEL, TARGET_ARCHITECTURE, then the feature's `design.md`.

## How a report over days flows

```text
 <id>.json "usageHistory"  ──►  UsageLog (DataSources)        one per login, built by
                                  reader · PriceList ·          ProviderFactory from the definition
                                  DayAggregator
                                       │
 popover opens (never in the background, #204)
        │                              ▼
 account.usageHistory?.days(in: .last(14))   ──►  [DailyUsageStat]   (closed days from the ledger)
        │
        ▼
 WeeklyReport(days:)            a rich value in Modules/Quotas: deltas, percentages, formatting
        │
        ▼
 WeeklyCardView                 renders what the report says — never compares or counts
```

## Workflow

```
Phase 0: Place it and design it (get user approval)
    ↓
Phase 1: The report value + tests (TDD Red→Green)
    ↓
Phase 2: Only if needed — the definition's usageHistory, a new reader, or a capability
    ↓
Phase 3: Mockup, card view, reading it on popover open
    ↓
Phase 4: Verify, screenshots on mock data, docs
```

---

## Phase 0: Place it and design it (MANDATORY)

### Step 1: Define the report

- **What does the person want to know?** In their words (USER_JOURNEYS).
- **Which kind is it?** The table above.
- **Which days?** `DateRange` (`.last(n)`, a week, today vs yesterday).
- **Which logins?** A report is per login — two logins are two reports, never summed.
- **How many cards?** One per metric, or one combined card.

### Step 2: Diagram it

```
Example: this week vs last week, per login

┌────────────────────────────────────────────────────────────────────┐
│  Providers (module)           Quotas (module)        App           │
│                                                                    │
│  account.usageHistory   ─►  WeeklyReport(days:)  ─►  WeeklyCardView │
│   .days(in: .last(14))       thisWeek / lastWeek      × 3 metrics   │
│   → [DailyUsageStat]         deltas, %, formatted                   │
│                                                                    │
│  No reading code: claude.json's usageHistory already reads the logs│
└────────────────────────────────────────────────────────────────────┘
```

### Step 3: The pieces

| Piece | Module | One job | Test |
|---|---|---|---|
| `WeeklyReport` | `Quotas` | turns days into the comparison the card shows | `Tests/DomainTests/<Feature>/` |
| `WeeklyCardView` | `App` | renders it | AppTests / screenshots |
| *(only if needed)* `usageHistory` block, a reader, a capability | definition / `DataSources` / `Providers` | — | golden tests / `DataSourcesTests` / `ProvidersTests` |

### Step 4: Mockup and approval

A UI change gets a mockup in `design-concept/<feature>/` on mock data first
(AGENTS.md). Present the doc change, the diagram, the pieces an

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.