Skip to content

Commit 09302fd

Browse files
docs: clarify unified source configuration contracts
List the public source options, document colon-form config precedence, and state the override-free base requirement for pricing copies. Co-authored-by: viniciusdsandrade <[email protected]>
1 parent 52df41e commit 09302fd

3 files changed

Lines changed: 7 additions & 4 deletions

File tree

‎docs/guide/config-files.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -287,17 +287,18 @@ ccusage antigravity daily
287287
ccusage zcode daily
288288
```
289289

290-
Source-specific settings are also applied when running unified reports such as `ccusage daily`. Each source uses the same merged options as its focused command: global `defaults`, `commands.<report>`, `<source>.defaults`, and `<source>.commands.<report>`, with command-line flags taking precedence for every source. Set `offline` and `pricingOverrides` globally to share them across sources, or in a source section to specialize them. Each source groups dates with its resolved timezone before rows are combined, so sources with different timezones can place the same event on adjacent calendar dates.
290+
Source-specific settings are also applied when running unified reports such as `ccusage daily`. Each source uses the same merged options as its focused command: global `defaults`, `commands.<report>`, `commands."<source>:<report>"`, `<source>.defaults`, and `<source>.commands.<report>`, with command-line flags taking precedence for every source. Set `offline` and `pricingOverrides` globally to share them across sources, or in a source section to specialize them. Each source groups dates with its resolved timezone before rows are combined, so sources with different timezones can place the same event on adjacent calendar dates.
291291

292292
Use `pi.stores` for additional pi-format session stores, such as tools or forks that write sessions outside `~/.pi/agent/sessions`. Named stores are additive to the default `pi` agent in unified reports, use their own agent name in JSON and tables, and prefix models with `[name]` followed by a space. Store names must match `^[a-z][a-z0-9_-]{0,31}$`, must be unique, and cannot use a built-in agent name. Each store path can be one sessions directory or a comma-separated list; `~` is expanded for store paths, nonexistent paths are treated as empty, and resolved paths that overlap the default `pi` store or another named store — including one path nested inside another — are rejected. They do not create focused commands such as `ccusage omp daily`; `PI_AGENT_DIR`, `--pi-path`, and `pi.defaults.piPath` still affect only the default `pi` agent.
293293

294294
For a source-focused command, or each source within a unified report, options are applied in this order:
295295

296296
1. `defaults`
297297
2. `commands.<report>`
298-
3. `<source>.defaults`
299-
4. `<source>.commands.<report>`
300-
5. Command-line arguments
298+
3. `commands."<source>:<report>"`
299+
4. `<source>.defaults`
300+
5. `<source>.commands.<report>`
301+
6. Command-line arguments
301302

302303
## Command-Specific Options
303304

‎rust/crates/ccusage-cli/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ renderer, and the help JSON live in `ccusage-cli-parser` instead.
2828
- `types::SessionArgs`
2929
- `types::SharedArgs`
3030
- `types::SortOrder`
31+
- `types::SourceArgs`
3132
- `types::StatuslineArgs`
3233
- `types::VisualBurnRate`
3334
- `types::WeekDay`

‎rust/crates/ccusage-core/src/pricing.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1081,6 +1081,7 @@ impl PricingMap {
10811081
///
10821082
/// This lets callers share one fetched or embedded base between reports
10831083
/// while keeping each report's override cache separate.
1084+
/// The base map must not already contain user overrides.
10841085
pub fn with_user_overrides<'a, I>(&self, overrides: I) -> Self
10851086
where
10861087
I: IntoIterator<Item = (&'a String, &'a PricingOverride)>,

0 commit comments

Comments
 (0)