cctally 1.96.1 → 1.97.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.97.0] - 2026-08-13
+
+### Changed
+- Reveal-mode share exports now allow project directories whose basename is exactly a UUID or source-root-shaped hex token, while the same value outside a typed project field still fails the document-wide privacy guard (#521).
+- Fix UI-QA provenance for subagent-driven UI work by allowing a durable report-only certification commit to name and verify the exact already-committed target, and stop unrelated linked worktrees from perturbing the QA cleanup fingerprint (#558).
+- The dashboard's `All` headline now states a quantity you can check. It is the sum of each provider's own current billing period — Claude's subscription week plus Codex's native seven-day cycle — instead of a thirty-day Claude accounting rollup added to a seven-day Codex cycle under no period label, which on one production install read $18,401.71 beside provider tabs showing about $1,704 and about $4,108. The heading names the cycles it covers and names only the providers actually contributing, each provider block carries its own labelled reset, and the per-provider split is on the hero itself rather than behind a modal. Because the two legs are each provider's own cycle, the figure steps down twice a week at two different reset instants and is not comparable against itself across a reset (#556).
+- The `All` staleness marker no longer sits on the figure permanently. The dashboard's `hero` freshness axis now means "the current cycle resolves and its counters are publishable" rather than "how old the last percent observation is", and percent age moved to the `quota` axis, which is what it always described. The two axes were being combined across clocks forty times apart — ninety seconds against one hour — so the marker was on almost always. A published combined figure is now qualified only by a real qualification, and the self-contradicting pairing of "combined totals are unavailable" with "combined totals use retained actuals" is gone (#556).
+- On an install with more than one account on either provider, the `All` combined total is withheld with a named reason saying which provider has several accounts on separate cycles, and points at the per-account cards that carry each account's own spend. Publishing a single number there would have reproduced the same defect inside the decorated path, because it could not be reconciled against any tab. A count that cannot be read withholds the figure too, rather than assuming a single account (#556).
+
+### Fixed
+- Deep doctor diagnostics and `db journal-repair` now preserve the same physical journal positions as rebuild when fingerprinting structural correction violations, so irrelevant observations can no longer make one path reject another path's durable resolution audit (#508).
+- Root and setup help now describe both Claude and Codex, expose provider-aware `--source` analytics and native Codex quota commands, and name setup-managed Codex handlers (#555).
+- The concurrent stats-heal writer-storm regression now waits for the detached worker's terminal success event before reading the rebuilt index, instead of racing publication artifacts that can become visible while the worker is still finishing under load (#559).
+- CI no longer reports a reader jump as stranded when the reader is merely still travelling toward it. The transient-drain-failure regression measured whether the linked turn sat inside the reader viewport as soon as the turn mounted, but mounting only means the backward walk has reached it, not that the walk has stopped scrolling; the measurement now waits for the scroll to settle, the way every other jump assertion in that suite already did.
+- The dashboard refreshes far more often on installs with a large Codex history, so newly recorded milestones and every other panel stop lagging minutes behind the database. A per-file lookup in the Codex source panel matched on the provider root alone, and because a machine normally has exactly one Codex root that lookup read every Codex usage row for every rollout file. On one real store of 2,324 files and 151,903 entries it took 57 seconds of an 84-second snapshot rebuild, which the dashboard's work-proportional cooldown then doubled into a staleness window of roughly 170 seconds. A composite index over the two columns the lookup actually matches makes it linear again, measured at 57.20s to 0.208s, which cuts the whole rebuild to about 32 seconds. The index is re-derivable, so an existing cache gains it on the next open with no migration, no data rewrite and no measurable size increase.
+
+## [1.96.2] - 2026-08-13
+
+### Fixed
+- CI no longer mistakes loaded-runner latency for a transcript-rebuild phase failure, a hung dashboard budget reconcile, a fake app-server that failed to start, or a writer-storm regression when readers remain healthy relative to both the uncontended baseline and concurrent writers.
+- Settings section links now scroll only the content pane, keep the modal chrome visible, and select the requested section consistently in Safari.
+- Claude Sonnet 5 usage now uses its permanent $2/$10 per-million-token rate, and Claude Mythos 5 plus retained Mythos Preview usage are no longer left unpriced.
+
 ## [1.96.1] - 2026-08-13
 
 ### Fixed
@@ -45,6 +68,7 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - The sanctioned local test escape hatch now runs the same contract as a remote run. `CCTALLY_TEST_LOCAL=1` previously left the `agentmem`-gated tests skipping while every remote run required them, so a local green and a remote green were different claims and no document said so. The local path now pins the same policy. If `agentmem` is genuinely absent the run still completes rather than dying, but it states which contract it ran and how many tests that skipped, and classifies itself non-authoritative under a named reason (#529).
 
 ### Fixed
+- Share charts now use an AA-compliant light warning colour and keep stacked segments distinguishable without colour (#524).
 - Remote test routing no longer mistakes runners last provisioned by different branches for a toolchain divergence; parity now compares the caller's declared Python closure while retaining live host-runtime checks (#548).
 - The stats-corruption epic test now waits for the heal worker's terminal outcome instead of racing the earlier request-marker cleanup, and its maintenance-holder handshake uses bounded readiness and release pipes rather than wall-clock guesses. Sanitized pytest failure extracts now retain safe assertion structure and normalized traceback locations while continuing to redact private paths and dynamic values (#552).
 - Remote test runs now refuse a conflicted checkout before contacting a runner, name the unmerged git index and its normal `git add` recovery, and always explain a manifest mismatch even when duplicate path records were the only difference (#550).

package/bin/_cctally_dashboard_envelope.py

@@ -1188,6 +1188,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
 
     week_lbl: "str | None" = None
     reset_at_utc: "dt.datetime | None" = None
+    week_start_at_utc: "dt.datetime | None" = None
     if cw is not None:
         ws = getattr(cw, "week_start_at", None)
         we = getattr(cw, "week_end_at", None)
@@ -1203,6 +1204,7 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         elif ws is not None:
             week_lbl = format_display_dt(ws, resolved_tz_obj, fmt='%b %d', suffix=False)
         reset_at_utc = we
+        week_start_at_utc = ws
 
     # Header forecast_pct should match the projection that drove the
     # verdict pill next to it. The View (issue #57) carries the
@@ -1616,7 +1618,19 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                     None if cw.five_hour_resets_at is None
                     else max(0, int((cw.five_hour_resets_at - now_utc).total_seconds())),
                 "spent_usd":                cw.spent_usd,
+                # #556 S1 §3.3 — the token half of the same accumulation pass
+                # that produced `spent_usd`. `getattr` keeps legacy fixture
+                # modules that construct `TuiCurrentWeek` without the field
+                # serializing, the same way `five_hour_block` does.
+                "total_tokens":             getattr(cw, "total_tokens", 0),
                 "dollar_per_pct":           cw.dollars_per_percent,
+                # #556 S1 §3.5 — the effective cycle start, the companion of
+                # the already-published `reset_at_utc` end. Composition needs
+                # BOTH bounds to label the Claude leg's period, and the source
+                # version needs them to detect a nominal rollover (§3.6).
+                # Effective, not nominal: `_tui_build_current_week` stores this
+                # AFTER `_apply_midweek_reset_override`.
+                "week_start_at":            _iso_z(week_start_at_utc),
                 "reset_at_utc":             _iso_z(reset_at_utc),
                 "reset_in_sec":
                     None if reset_at_utc is None

package/bin/_cctally_dashboard_share.py

@@ -50,7 +50,6 @@ from _cctally_config import save_config, _load_config_unlocked
 from _lib_fmt import stable_sum
 from _lib_pricing import _calculate_entry_cost, claude_usage_dict
 from _lib_five_hour import _canonical_5h_window_key
-from _lib_dashboard_sources import source_domain_freshness
 from _lib_display_tz import _resolve_tz, resolve_display_tz_name
 
 
@@ -1783,12 +1782,33 @@ def _build_codex_source_share_snapshot(ls, *, state, panel: str,
     )
 
 
+def _share_current_week_evidence_is_stale(state) -> bool:
+    """Whether ONE provider's own current-cycle evidence is stale (#556 §4.7).
+
+    This used to read the shared ``domain_freshness.hero`` axis, which #556 S1
+    repointed to accounting resolvability. The aggregate ``quota`` axis is not
+    the substitute: a stale five-hour row stales it independently of the weekly
+    cycle this note describes. So each provider is read on its own field —
+    Claude's percent-observation label under ``hero.current_week.freshness``,
+    Codex's additive ``hero.cycle_freshness``, which is omitted while fresh.
+    """
+    data = getattr(state, "data", None)
+    hero = data.get("hero") if isinstance(data, Mapping) else None
+    if not isinstance(hero, Mapping):
+        return False
+    if getattr(state, "source", None) == "claude":
+        current_week = hero.get("current_week")
+        freshness = (
+            current_week.get("freshness")
+            if isinstance(current_week, Mapping) else None
+        )
+        return isinstance(freshness, Mapping) and freshness.get("label") == "stale"
+    return hero.get("cycle_freshness") == "stale"
+
+
 def _share_apply_current_week_freshness(snapshot, state, panel: str):
     """Qualify retained current-week actuals with provider-local evidence age."""
-    if (
-        panel != "current-week"
-        or source_domain_freshness(state, "hero") != "stale"
-    ):
+    if panel != "current-week" or not _share_current_week_evidence_is_stale(state):
         return snapshot
     provider = "Claude" if state.source == "claude" else "Codex"
     note = (

package/bin/_cctally_dashboard_sources.py

@@ -1261,6 +1261,24 @@ def _codex_cache_report_wire(
     )
 
 
+#: Per-file terminal thread aliases, joined to their first accounting entry.
+#: The ``(source_root_key, source_path)`` join predicate needs the composite
+#: ``idx_codex_entries_root_path`` to stay linear: a single-column root index
+#: cannot discriminate when every rollout resolves to one provider root, so the
+#: join degenerates to files x entries. Module-level so the query-plan
+#: regression asserts THIS text rather than a copy that can drift from it.
+_CODEX_FILE_ALIAS_SQL = (
+    "SELECT f.source_root_key, f.path, f.last_native_thread_id, "
+    "f.last_session_id, MIN(e.timestamp_utc) "
+    "FROM codex_session_files AS f "
+    "LEFT JOIN codex_session_entries AS e "
+    "ON e.source_root_key=f.source_root_key AND e.source_path=f.path "
+    "WHERE f.last_native_thread_id IS NOT NULL AND f.last_native_thread_id != '' "
+    "GROUP BY f.source_root_key, f.path, f.last_native_thread_id, f.last_session_id "
+    "ORDER BY f.last_ingested_at DESC, f.path DESC"
+)
+
+
 def _codex_conversation_metadata(
     cache_conn: sqlite3.Connection,
 ) -> dict[tuple[str, str], dict[str, object]]:
@@ -1302,16 +1320,7 @@ def _codex_conversation_metadata(
                 cwd, git_json, first_seen_at, _last_seen_at,
             ) in core_rows
         )
-        file_aliases = tuple(cache_conn.execute(
-            "SELECT f.source_root_key, f.path, f.last_native_thread_id, "
-            "f.last_session_id, MIN(e.timestamp_utc) "
-            "FROM codex_session_files AS f "
-            "LEFT JOIN codex_session_entries AS e "
-            "ON e.source_root_key=f.source_root_key AND e.source_path=f.path "
-            "WHERE f.last_native_thread_id IS NOT NULL AND f.last_native_thread_id != '' "
-            "GROUP BY f.source_root_key, f.path, f.last_native_thread_id, f.last_session_id "
-            "ORDER BY f.last_ingested_at DESC, f.path DESC"
-        ))
+        file_aliases = tuple(cache_conn.execute(_CODEX_FILE_ALIAS_SQL))
         native_ids = tuple(sorted({
             str(native_thread_id) for _, _, native_thread_id, *_ in rows
             if isinstance(native_thread_id, str) and native_thread_id
@@ -2393,6 +2402,11 @@ def refresh_codex_source_clock(
                 "hero",
             ),)
             availability = "partial"
+            # #556 S1 §4.1: an EXPIRED boundary is exactly the state the
+            # accounting axis reports as stale. Build time can never see it
+            # (`_resolve_codex_weekly_cycle` retains only `resets_at > now`),
+            # so this clock is the only writer of that value.
+            domain_freshness["hero"] = "stale"
             cycle_changed = True
         # 3. budget last
         if refreshed_budget is not None:
@@ -2411,6 +2425,10 @@ def refresh_codex_source_clock(
         data=data,
         domain_freshness=domain_freshness,
         clock_data=state.clock_data,
+        # #556 S1 §3.8: this constructor lists every field explicitly, so an
+        # omission silently drops the authoritative account count and makes the
+        # combined figure fail closed on an idle tick that changed nothing else.
+        account_scope=state.account_scope,
         private_session_labels=state.private_session_labels,
     )
     return state if refreshed_state == state else refreshed_state
@@ -3408,7 +3426,6 @@ def build_codex_source_state(
             cache_conn=context.cache_conn,
         )
     budget_entries = _codex_entries_from_accounting(accounting_entries)
-    cycle_reason: str | None = None
     cycles_all: list[CodexCycleBoundary] = []
     try:
         # Per-account list (#341 Task 2). ``cycles_all`` drives the per-account
@@ -3419,9 +3436,12 @@ def build_codex_source_state(
         # `conflicting`.
         cycles_all = _resolve_codex_weekly_cycle(quota_observations, context.now_utc)
         cycle = cycles_all[0] if cycles_all else None
-    except CodexCycleUnavailable as exc:
+    except CodexCycleUnavailable:
+        # #556 S1 §4.1: the reason no longer moves a freshness axis. A
+        # `stale` reason is observation AGE, which `quota` owns; every reason
+        # here leaves `cycle` unresolved, which `cycle_failure` below turns
+        # into the hero failure the accounting axis actually reports.
         cycle = None
-        cycle_reason = exc.reason
     cycle_failure = cycle is None and has_cached_codex_accounting_entries(
         cache_conn=context.cache_conn,
     )
@@ -3826,16 +3846,17 @@ def build_codex_source_state(
                if ingest_backlog is not None else {}),
         },
         domain_freshness={
-            "hero": (
-                "stale"
-                if cycle_reason == "stale"
-                or (
-                    cycle is not None
-                    and not hero_failure
-                    and cycle.evidence_stale
-                )
-                else "fresh"
-            ),
+            # #556 S1 §4.1: `hero` means current-cycle ACCOUNTING
+            # resolvability, not observation age. A stale-but-still-future
+            # boundary stays RESOLVED — the spend it bounds is correct, and
+            # Codex has no background quota poll, so `stale_after_seconds`
+            # (3600) makes an idle weekly observation stale within the hour
+            # while nothing about the accounting changed. The percent age is
+            # already carried by `quota` below and by the additive hero-local
+            # `cycle_freshness` field. `_resolve_codex_weekly_cycle` retains
+            # only boundaries with `resets_at > now`, so a resolved cycle is
+            # never expired at build time; the idle clock owns expiry.
+            "hero": "stale" if hero_failure else "fresh",
             "quota": (
                 "stale"
                 if quota["summary"]["freshness"] == "stale"

package/bin/_cctally_db.py

@@ -4310,6 +4310,16 @@ def _apply_cache_schema(conn: sqlite3.Connection) -> None:
         "CREATE INDEX IF NOT EXISTS idx_codex_entries_ts_root_conversation "
         "ON codex_session_entries(timestamp_utc, source_root_key, conversation_key)"
     )
+    # The per-file alias join in `_codex_conversation_metadata` matches on
+    # (source_root_key, source_path). `idx_codex_entries_source_root` cannot
+    # serve it: a machine normally has ONE provider root, so a root-only search
+    # visits every entry row for every file and the join costs files x entries
+    # on every dashboard snapshot build. Re-derivable, so it belongs on the
+    # unconditional path with the S3 index above rather than in a migration.
+    conn.execute(
+        "CREATE INDEX IF NOT EXISTS idx_codex_entries_root_path "
+        "ON codex_session_entries(source_root_key, source_path)"
+    )
     # The per-file terminal thread facts seed a later append without rereading
     # the prefix. They are nullable for old cache rows; migration 024 never
     # fabricates these source facts and instead clears/rederives them.

package/bin/_cctally_doctor.py

@@ -38,6 +38,7 @@ import sys
 
 import _cctally_core
 import _lib_changelog
+import _lib_journal_router
 from _cctally_core import _now_utc, eprint, now_utc_iso, parse_iso_datetime
 from _lib_dashboard_json import encode_dashboard_json
 
@@ -46,10 +47,10 @@ from _lib_dashboard_json import encode_dashboard_json
 #: (`_lib_journal.resolve_effective_events`) reads only `evt`, `correction` and
 #: `correction_batch`; `op` is kept because the rebuild-equivalent account
 #: normalization is defined over evt/op records. Everything else — above all the
-#: `obs` lines, ~97% of a real journal — is dropped as it is decoded, so the deep
-#: gather's peak RSS tracks the decision history rather than the whole journal.
-_CONFLICT_SCAN_RECORD_TYPES = frozenset(
-    {"evt", "correction", "correction_batch", "op"})
+#: `obs` lines, ~97% of a real journal — becomes a `None` positional slot as it
+#: is decoded, so peak RSS tracks decision dictionaries plus one pointer per
+#: decoded line rather than the whole decoded journal.
+_CONFLICT_SCAN_RECORD_TYPES = _lib_journal_router.RETAINED_RECORD_TYPES
 
 #: Doctor needs only recent evidence for this diagnostic. Bound both line count
 #: and bytes so a corrupt single-line file cannot defeat the tail limit.
@@ -1798,10 +1799,13 @@ def _doctor_gather_state_impl(
                         # RETAIN ONLY what the selector consumes. `obs` lines are
                         # ~97% of a real journal (984k of 1.02M) and
                         # `resolve_effective_events` ignores them entirely —
-                        # keeping them cost 4.3 GB of peak RSS for an identical
-                        # result (#374 review).
-                        if record.get("t") in _CONFLICT_SCAN_RECORD_TYPES:
-                            decoded_records.append(record)
+                        # keeping their dictionaries cost 4.3 GB of peak RSS for
+                        # an identical result (#374 review). They still consume a
+                        # lightweight slot because their physical sequence is
+                        # part of three durable violation fingerprints (#508).
+                        decoded_records.append(
+                            _lib_journal_router.selector_slot(record)
+                        )
                         prior_high_water = (
                             seg,
                             offset + len(raw) + 1,
@@ -1821,8 +1825,9 @@ def _doctor_gather_state_impl(
                         else _jr.resolve_cutover_claude_account()
                     )
                     for record in decoded_records:
-                        _jr._normalize_legacy_account_stamp(
-                            record, cutover_claude)
+                        if record is not None:
+                            _jr._normalize_legacy_account_stamp(
+                                record, cutover_claude)
                     selection = _jl.resolve_effective_events(
                         decoded_records,
                         protocol_prefix_evidence=protocol_evidence,

package/bin/_cctally_journal_repair.py

@@ -54,10 +54,10 @@ def _read_prefix(high_water):
     inline exactly as `rebuild_stats_index` captures it. Before this, those were
     four separate whole-prefix traversals on top of this one (#496 S5 §4).
 
-    Every record stays decoded. Unlike the rebuild, the selector here feeds an
-    acknowledgement the repair command may then mint, and unlike the rebuild's
-    filtered retention there is no placeholder scheme to keep the `enumerate`
-    numbering identical — so the list is unfiltered, exactly as before.
+    Every decoded line contributes one selector slot. Decision records stay
+    decoded; observations and other irrelevant records become ``None``
+    placeholders, preserving the `enumerate` numbering that durable violation
+    fingerprints hash without retaining whole-prefix decoded history.
     """
     if high_water is None:
         return [], (), None, {}
@@ -106,7 +106,7 @@ def _read_prefix(high_water):
             and record.get("id") == _journal.CUTOVER_OP_ID
         ):
             cutover_captured = _journal._cutover_value_of(record)
-        records.append(record)
+        records.append(_lib_journal_router.selector_slot(record))
         prior_high_water = record_end
     prefix_hash = hasher.digest_at(high_water)
     # The accumulator buffers the segment it is reading — 410 MB on the
@@ -136,7 +136,8 @@ def _read_prefix(high_water):
     else:
         cutover_claude = cutover_captured
     for record in records:
-        _journal._normalize_legacy_account_stamp(record, cutover_claude)
+        if record is not None:
+            _journal._normalize_legacy_account_stamp(record, cutover_claude)
     return records, tuple(evidence), prefix_hash, audit_ends
 
 

package/bin/_cctally_parser.py

@@ -58,6 +58,24 @@ class CLIHelpFormatter(
         super().__init__(prog, **kwargs)  # type: ignore[arg-type]
 
 
+_PHYSICAL_PROVIDER_SOURCES = ("claude", "codex")
+
+
+def _analytics_source_choices() -> tuple[str, ...]:
+    """Return physical providers plus the provider-separated combined view."""
+    return (*_PHYSICAL_PROVIDER_SOURCES, "all")
+
+
+def _provider_display_names() -> str:
+    """Render the canonical physical-provider tuple for user-facing help."""
+    labels = tuple(source.title() for source in _PHYSICAL_PROVIDER_SOURCES)
+    if len(labels) == 1:
+        return labels[0]
+    if len(labels) == 2:
+        return " and ".join(labels)
+    return f"{', '.join(labels[:-1])}, and {labels[-1]}"
+
+
 def _argparse_has_arg(parser, option_string: str) -> bool:
     """Return True if ``parser`` already registered ``option_string``."""
     for action in parser._actions:
@@ -288,11 +306,12 @@ def _add_source_args(
     """Attach the source selector or pin a nested provider alias."""
     if fixed_source is None:
         parser.add_argument(
-            "--source", choices=("claude", "codex", "all"), default="claude",
-            help="Analytics provider: claude (default), codex, or all.",
+            "--source", choices=_analytics_source_choices(),
+            default=_PHYSICAL_PROVIDER_SOURCES[0],
+            help="Analytics provider.",
         )
     else:
-        if fixed_source not in {"claude", "codex"}:
+        if fixed_source not in _PHYSICAL_PROVIDER_SOURCES:
             raise ValueError(f"unsupported fixed source {fixed_source!r}")
         parser.set_defaults(source=fixed_source)
     if speed:
@@ -2717,8 +2736,9 @@ def _build_setup_parser(subparsers, name, *, help_text, xref=None):
         formatter_class=CLIHelpFormatter,
         description=textwrap.dedent(
                     """\
-                    Install cctally into Claude Code by adding hook entries to
-                    ~/.claude/settings.json (additive, idempotent) and creating
+                    Install cctally for local providers by adding Claude hook entries
+                    to ~/.claude/settings.json and native Codex handlers to every
+                    configured Codex home (all additive and idempotent). Also create
                     user-facing symlinks under ~/.local/bin/.
 
                     Modes (mutually exclusive):
@@ -2823,7 +2843,7 @@ def _build_transcript_parser(subparsers, name, *, help_text, xref=None):
         formatter_class=CLIHelpFormatter)
     t_search.add_argument("query", metavar="QUERY", help="Search text")
     t_search.add_argument(
-        "--source", choices=("claude", "codex"), default="claude",
+        "--source", choices=_PHYSICAL_PROVIDER_SOURCES, default="claude",
         help="Which provider's conversations to search (default: claude)")
     t_search.add_argument(
         "--account", metavar="REF", default=None,
@@ -3270,7 +3290,7 @@ def _build_hook_tick_parser(subparsers, name, *, help_text, xref=None):
                     help=argparse.SUPPRESS)  # JSON string fed to mock fetch (tests only)
     ht.add_argument("--foreground", action="store_true",
                     help=argparse.SUPPRESS)  # Codex native hook wrapper
-    ht.add_argument("--source", choices=("claude", "codex"), default="claude",
+    ht.add_argument("--source", choices=_PHYSICAL_PROVIDER_SOURCES, default="claude",
                     help=argparse.SUPPRESS)  # setup-managed native Codex hook
     ht.set_defaults(func=c.cmd_hook_tick)
 
@@ -3572,7 +3592,7 @@ _REGISTRATION = (
     _Reg('account', _build_account_parser, "Inspect per-provider account registry (list / show / label)", None, None),
     _Reg('telemetry', _build_telemetry_parser, "Show or change anonymous install-count telemetry", None, None),
     _Reg('alerts', _build_alerts_parser, "Manage threshold alerts", None, None),
-    _Reg('setup', _build_setup_parser, "Install cctally into Claude Code (hooks + symlinks)", None, None),
+    _Reg('setup', _build_setup_parser, "Install provider hooks/handlers + symlinks", None, None),
     _Reg('db', _build_db_parser, "Migration / DB management (status, skip, unskip)", None, None),
     _Reg('doctor', _build_doctor_parser, "Diagnose data freshness and install state", None, None),
     _Reg('pricing-check', _build_pricing_check_parser, "Detect stale or missing embedded model pricing", None, None),
@@ -3592,28 +3612,33 @@ _REGISTRATION = (
 
 def build_parser() -> argparse.ArgumentParser:
     c = _cctally()
+    providers = _provider_display_names()
+    source_choices = ",".join(_analytics_source_choices())
+    quick_start_reports = "\n".join(
+        f"  cctally report --source {source}"
+        for source in _PHYSICAL_PROVIDER_SOURCES
+    )
     p = argparse.ArgumentParser(
         prog="cctally",
         formatter_class=CLIHelpFormatter,
         description=textwrap.dedent(
-            """\
-            Track Claude subscription weekly usage percent and weekly cost
-            in a local SQLite database.
+            f"""\
+            Track {providers} subscription usage and local USD cost in SQLite.
 
             Data flow:
-              1) Claude Code status line captures rate limit data after each API call.
-              2) record-usage stores usage snapshots and triggers percent milestones.
-              3) sync-week computes weekly USD cost from Claude Code session data.
-              4) report computes dollars per 1% and shows trend history.
+              1) Claude Code hooks and status lines retain Claude usage and sessions.
+              2) Native Codex handlers retain Codex sessions and quota windows.
+              3) Provider-aware project, diff, range-cost, cache-report, and report
+                 commands accept --source {{{source_choices}}}.
+              4) Provider-native reports keep {providers} quota percentages and
+                 reset windows separate; `cctally codex quota` exposes Codex windows.
             """
         ),
-        epilog=textwrap.dedent(
-            """\
-            Quick start:
-              # Add record-usage call to ~/.claude/statusline-command.sh (see record-usage --help)
-              cctally sync-week
-              cctally report
-            """
+        epilog=(
+            "Quick start:\n"
+            "  cctally setup\n"
+            f"{quick_start_reports}\n"
+            "  cctally codex quota statusline"
         ),
     )
     p.add_argument(