cctally 1.22.0 → 1.22.1

package/bin/cctally

@@ -349,23 +349,26 @@ format_display_dt = _lib_display_tz.format_display_dt
 _argparse_tz = _lib_display_tz._argparse_tz
 
 
-def _nonneg_int(raw: str) -> int:
-    """argparse `type=` validator for non-negative integer flags (issue #89).
-
-    Used by ``--debug-samples`` so a negative N is rejected at parse time
-    rather than silently coerced inside the helper. Raises
-    ``argparse.ArgumentTypeError`` so argparse surfaces the message under
-    the standard ``argument <flag>:`` prefix.
-    """
-    try:
-        n = int(raw)
-    except ValueError:
-        raise argparse.ArgumentTypeError(
-            f"must be a non-negative integer, got '{raw}'"
-        )
-    if n < 0:
-        raise argparse.ArgumentTypeError(f"must be >= 0, got {n}")
-    return n
+_cctally_parser = _load_sibling("_cctally_parser")
+build_parser = _cctally_parser.build_parser
+_nonneg_int = _cctally_parser._nonneg_int
+CLIHelpFormatter = _cctally_parser.CLIHelpFormatter
+_argparse_has_arg = _cctally_parser._argparse_has_arg
+_add_mode_arg = _cctally_parser._add_mode_arg
+_add_ccusage_alias_args = _cctally_parser._add_ccusage_alias_args
+_add_codex_shared_args = _cctally_parser._add_codex_shared_args
+_add_share_args = _cctally_parser._add_share_args
+_share_validate_args = _cctally_parser._share_validate_args
+_build_daily_parser = _cctally_parser._build_daily_parser
+_build_monthly_parser = _cctally_parser._build_monthly_parser
+_build_weekly_parser = _cctally_parser._build_weekly_parser
+_build_session_parser = _cctally_parser._build_session_parser
+_build_blocks_parser = _cctally_parser._build_blocks_parser
+_build_statusline_parser = _cctally_parser._build_statusline_parser
+_build_codex_daily_parser = _cctally_parser._build_codex_daily_parser
+_build_codex_monthly_parser = _cctally_parser._build_codex_monthly_parser
+_build_codex_weekly_parser = _cctally_parser._build_codex_weekly_parser
+_build_codex_session_parser = _cctally_parser._build_codex_session_parser
 
 
 _lib_alerts_payload = _load_sibling("_lib_alerts_payload")
@@ -498,6 +501,42 @@ _render_project_table = _lib_render._render_project_table
 _five_hour_blocks_to_json = _lib_render._five_hour_blocks_to_json
 _render_five_hour_blocks_table = _lib_render._render_five_hour_blocks_table
 
+# Eager re-export of bin/_cctally_share.py (eager sibling holding the
+# share destination/emit path + the _build_*_snapshot builders + the
+# _share_* helpers). Loaded here, after _lib_render / _lib_display_tz /
+# _lib_changelog (its three sibling deps), so its module-top imports
+# resolve. Every moved symbol is re-bound onto cctally's __dict__ so the
+# cmd_* handlers' bare `_share_render_and_emit(...)` / `_build_*_snapshot(...)`
+# calls, the staying _build_budget_snapshot dispatch, and the dashboard's
+# `sys.modules["cctally"].X` share thunks all resolve to the same objects.
+_cctally_share = _load_sibling("_cctally_share")
+_DOWNLOADS_HOME_HINT_EMITTED = _cctally_share._DOWNLOADS_HOME_HINT_EMITTED
+_share_resolve_download_dir = _cctally_share._share_resolve_download_dir
+_share_unique_path = _cctally_share._share_unique_path
+_resolve_destination = _cctally_share._resolve_destination
+_emit = _cctally_share._emit
+_share_load_lib = _cctally_share._share_load_lib
+_share_now_utc = _cctally_share._share_now_utc
+_share_now_utc_iso = _cctally_share._share_now_utc_iso
+_SHARE_HISTORY_RING_CAP = _cctally_share._SHARE_HISTORY_RING_CAP
+_share_history_recipe_id = _cctally_share._share_history_recipe_id
+_share_resolve_version = _cctally_share._share_resolve_version
+_share_period_label = _cctally_share._share_period_label
+_share_parse_date_to_dt = _cctally_share._share_parse_date_to_dt
+_share_display_tz_label = _cctally_share._share_display_tz_label
+_build_report_snapshot = _cctally_share._build_report_snapshot
+_build_daily_snapshot = _cctally_share._build_daily_snapshot
+_build_monthly_snapshot = _cctally_share._build_monthly_snapshot
+_build_weekly_snapshot = _cctally_share._build_weekly_snapshot
+_build_forecast_snapshot = _cctally_share._build_forecast_snapshot
+_build_project_snapshot = _cctally_share._build_project_snapshot
+_build_five_hour_blocks_snapshot = _cctally_share._build_five_hour_blocks_snapshot
+_session_disambiguate_labels = _cctally_share._session_disambiguate_labels
+_build_session_snapshot = _cctally_share._build_session_snapshot
+_share_iso = _cctally_share._share_iso
+_share_render_and_emit = _cctally_share._share_render_and_emit
+_share_open_file = _cctally_share._share_open_file
+
 # Eager re-export of bin/_cctally_setup.py (lazy I/O sibling that loads
 # at startup to keep `ns["cmd_setup"](...)` / `ns["_setup_X"](...)`
 # direct-dict test patterns working — dict-key access on `mod.__dict__`
@@ -11013,17 +11052,6 @@ def cmd_range_cost(args: argparse.Namespace) -> int:
     return 0
 
 
-class CLIHelpFormatter(
-    argparse.ArgumentDefaultsHelpFormatter,
-    argparse.RawDescriptionHelpFormatter,
-):
-    """Human-friendly formatter for multi-line help and default values."""
-
-    def __init__(self, prog: str, **kwargs: object) -> None:
-        kwargs.setdefault("max_help_position", 30)
-        super().__init__(prog, **kwargs)  # type: ignore[arg-type]
-
-
 # Legacy bespoke hook set — see docs/superpowers/specs/2026-05-09-auto-migrate-legacy-hooks-design.md
 _LEGACY_BESPOKE_HOOKS_DIR = pathlib.Path.home() / ".claude" / "hooks"
 _LEGACY_BESPOKE_COMMANDS: tuple[tuple[str, str], ...] = (
@@ -11828,4168 +11856,6 @@ def cmd_doctor(args: argparse.Namespace) -> int:
     return 2 if report.overall_severity == "fail" else 0
 
 
-def _argparse_has_arg(parser, option_string: str) -> bool:
-    """Return True if ``parser`` already registered ``option_string``."""
-    for action in parser._actions:
-        if option_string in (action.option_strings or ()):
-            return True
-    return False
-
-
-def _add_mode_arg(parser, *, noop: bool = False) -> None:
-    """Add ccusage's -m/--mode {auto,calculate,display} cost-source flag.
-
-    Standalone (not folded into _add_ccusage_alias_args) so it lands only
-    on the six Session-C reporting commands and never collides with
-    range-cost, which defines its own -m/--mode.
-
-    noop=True (five-hour-blocks only): the flag is accepted for surface
-    parity with `blocks` but does not alter numbers — that command's cost
-    is the authoritative materialized five_hour_blocks.total_cost_usd
-    computed at record-time (always auto semantics).
-    """
-    help_real = (
-        "Cost source: auto (recorded costUSD when present, else computed), "
-        "calculate (always compute from embedded pricing), display "
-        "(recorded costUSD only; $0 when absent). Default: auto."
-    )
-    help_noop = (
-        "Accepted for ccusage drop-in compat; no-op here — five-hour-blocks "
-        "cost is the authoritative materialized per-block value computed at "
-        "record-time. Default: auto."
-    )
-    parser.add_argument(
-        "-m", "--mode",
-        default="auto",
-        choices=["auto", "calculate", "display"],
-        help=help_noop if noop else help_real,
-    )
-
-
-def _add_ccusage_alias_args(parser, *, ansi_emit: bool) -> None:
-    """Attach the Session A ccusage alias surface to a Claude-cmd subparser.
-
-    Sibling to ``_add_codex_shared_args`` (declared inside ``build_parser``)
-    but tailored for Claude commands. Every flag is guarded with
-    ``_argparse_has_arg`` so existing per-parser declarations
-    (cache-report's ``--offline``, project / five-hour-blocks / diff's
-    ``--no-color``) do NOT cause ``argparse.ArgumentError`` — the helper
-    just skips the duplicate. This makes future collisions self-healing
-    when a contributor adds a Session A-managed flag directly on a
-    subparser.
-
-    Args:
-      parser:    the subparser to mutate.
-      ansi_emit: ``True`` for project + diff (the 2 real ANSI emitters).
-                 ``False`` for the other 8 in-scope cmds. Controls only
-                 the ``--color`` help text and whether ``--no-color`` is
-                 attempted as a fresh add (when ``ansi_emit=True`` we
-                 skip ``--no-color`` entirely — those parsers already
-                 declared it themselves).
-
-    Spec §7.1.2 / issue #86 Session A.
-    """
-
-    def _maybe_add(opt: str, *args, **kwargs):
-        if _argparse_has_arg(parser, opt):
-            return
-        parser.add_argument(opt, *args, **kwargs)
-
-    def _maybe_add2(opt1: str, opt2: str, *args, **kwargs):
-        # Two-form add (short + long) — skip if EITHER is present.
-        if _argparse_has_arg(parser, opt1) or _argparse_has_arg(parser, opt2):
-            return
-        parser.add_argument(opt1, opt2, *args, **kwargs)
-
-    _maybe_add2(
-        "-z", "--timezone", default=None, metavar="TZ",
-        help="Alias for --tz (drop-in compat with ccusage). When both "
-             "are supplied, --tz wins.",
-    )
-    _maybe_add2(
-        "-O", "--offline",
-        action=argparse.BooleanOptionalAction, default=False,
-        help="Accepted for ccusage drop-in compat; cctally is always offline.",
-    )
-    _maybe_add(
-        "--compact", action="store_true",
-        help="Force compact table layout regardless of terminal width.",
-    )
-    _maybe_add(
-        "--config", default=None, metavar="PATH",
-        help="Read config from PATH for this invocation only (no "
-             "mutation of the default config at "
-             "~/.local/share/cctally/config.json). Missing or invalid "
-             "PATH errors out with a clear message.",
-    )
-    _maybe_add2(
-        "-d", "--debug", action="store_true",
-        help="Emit a stderr 'Pricing Mismatch Debug Report' "
-             "(totals + per-model stats + sample discrepancies, "
-             "matching ccusage's --debug shape).",
-    )
-    _maybe_add(
-        "--debug-samples", type=_nonneg_int, default=5, metavar="N",
-        help="Cap on sample-discrepancy rows in the --debug report "
-             "(default 5; N=0 suppresses the sample block; "
-             "negatives rejected at parse time).",
-    )
-    _maybe_add(
-        "--single-thread", action="store_true",
-        help="Accepted for ccusage drop-in compat; cctally ingestion "
-             "is already single-threaded via the session-entry cache.",
-    )
-    if ansi_emit:
-        _maybe_add(
-            "--color", action="store_true", default=False,
-            help="Force ANSI color output (overrides NO_COLOR env). When "
-                 "neither --color nor --no-color is set, color is auto-"
-                 "detected from isatty() and NO_COLOR/FORCE_COLOR env.",
-        )
-        # --no-color already declared on these parsers; do nothing here.
-    else:
-        # No-op-for-compat surface (spec §7.3): these flags parse but do
-        # NOT flow through the color resolver on this command. Color (where
-        # the renderer emits any) follows the auto-detect — isatty() plus
-        # NO_COLOR / FORCE_COLOR env — so the help must NOT claim "no ANSI
-        # is emitted" (daily/monthly/weekly/blocks/session/cache-report DO
-        # emit auto-detected ANSI on a TTY; only the no-color env vars
-        # suppress it). Force/suppress color on the 2 real ANSI commands
-        # (project, diff) instead, or use NO_COLOR=1 / FORCE_COLOR=1.
-        _maybe_add(
-            "--color", action="store_true", default=False,
-            help="Accepted for ccusage drop-in compat; does not control "
-                 "this command's color. Color auto-detects from isatty() "
-                 "and honors NO_COLOR / FORCE_COLOR env.",
-        )
-        _maybe_add(
-            "--no-color", action="store_true", default=False,
-            help="Accepted for ccusage drop-in compat; does not suppress "
-                 "this command's color. Use NO_COLOR=1 env (or pipe stdout) "
-                 "to disable auto-detected ANSI.",
-        )
-
-
-def _add_codex_shared_args(parser: argparse.ArgumentParser) -> None:
-    """Register upstream `ccusage-codex sharedArgs` on a codex subparser.
-
-    Upstream sharedArgs (node_modules/@ccusage/codex/dist/index.js):
-      --timezone/-z, --locale/-l, --compact, --color, --noColor,
-      --offline/--no-offline.
-
-    Honored here: --timezone (dates + aggregation buckets) and
-    --compact (table layout). Accepted-but-no-op (stored on the
-    namespace for drop-in parity with upstream scripts): --locale
-    (we don't locale-format dates), --color / --noColor (we don't
-    emit ANSI codes today). --offline is accepted as a no-op too
-    (we are always offline); it uses BooleanOptionalAction so
-    `--no-offline` also parses cleanly. `-O` is kept as the short
-    form for offline for backward compat with earlier builds.
-    """
-    parser.add_argument(
-        "-z", "--timezone", default=None, metavar="TZ",
-        help="IANA timezone for date bucketing and Date/Last Activity cells.",
-    )
-    parser.add_argument(
-        "-l", "--locale", default=None, metavar="LOCALE",
-        help="Accepted for drop-in compat; no-op (dates are not locale-formatted).",
-    )
-    parser.add_argument(
-        "--compact", action="store_true",
-        help="Force compact table layout regardless of terminal width.",
-    )
-    parser.add_argument(
-        "--color", action="store_true",
-        help="Accepted for drop-in compat; no-op today (no ANSI escapes are emitted).",
-    )
-    parser.add_argument(
-        "--noColor", action="store_true", dest="no_color",
-        help="Accepted for drop-in compat; no-op today (no ANSI escapes are emitted).",
-    )
-    parser.add_argument(
-        "-O", "--offline", action=argparse.BooleanOptionalAction, default=False,
-        help="Accepted for drop-in compat with ccusage-codex; we are always offline.",
-    )
-    parser.add_argument(
-        "--speed", choices=("auto", "standard", "fast"), default="auto",
-        help="Codex pricing tier. auto (default) reads service_tier from "
-             "~/.codex/config.toml (fast|priority -> fast pricing); fast "
-             "forces the fast-tier multiplier; standard forces base pricing.",
-    )
-    parser.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. Overrides "
-             "config display.tz for this call. Takes precedence over "
-             "upstream's --timezone for drop-in parity.",
-    )
-    # Issue #92: codex parity for the #89 --debug surface. Codex JSONL
-    # has no recorded costUSD to diff against, so the report is the
-    # codex variant ("Codex Pricing Debug Report": totals + top-N
-    # highest computed-cost entries), wired via
-    # _emit_codex_debug_samples_if_set in each cmd_codex_* body.
-    parser.add_argument(
-        "-d", "--debug", action="store_true",
-        help="Emit a stderr 'Codex Pricing Debug Report' (totals + "
-             "the N highest computed-cost sample entries).",
-    )
-    parser.add_argument(
-        "--debug-samples", type=_nonneg_int, default=5, metavar="N",
-        help="Cap on top-entry sample rows in the --debug report "
-             "(default 5; N=0 suppresses the sample block; "
-             "negatives rejected at parse time).",
-    )
-
-
-def _add_share_args(parser, *, has_status_line: bool = False) -> None:
-    """Attach shareable-reports flags + format/json mutex to a subparser.
-
-    Idempotent — call exactly once per subparser. Caller MUST remove any
-    pre-existing ``--json`` (and ``--status-line`` for forecast) from the
-    subparser before invoking this helper, so the mutex group owns those
-    flags. Raises ``RuntimeError`` on contract violation — surfaces at
-    parser-build time (i.e., on every CLI invocation, including ``--help``)
-    instead of at the user invocation that hits the unguarded
-    ``--format --json`` combo. The prior shape silently skipped re-adding,
-    leaving the mutex unenforced for any future 9th share-enabled subparser
-    whose existing ``--json`` was accidentally left in place.
-    """
-    if _argparse_has_arg(parser, "--json"):
-        raise RuntimeError(
-            f"_add_share_args: parser {parser.prog!r} already has --json; "
-            "remove it before calling _add_share_args so mutex applies"
-        )
-    if has_status_line and _argparse_has_arg(parser, "--status-line"):
-        raise RuntimeError(
-            f"_add_share_args: parser {parser.prog!r} already has --status-line; "
-            "remove it before calling _add_share_args(has_status_line=True)"
-        )
-    output_group = parser.add_mutually_exclusive_group()
-    output_group.add_argument(
-        "--format", choices=("md", "html", "svg"),
-        help="Render output as shareable markdown, self-contained HTML, or SVG. "
-             "Default destination: md->stdout, html/svg->~/Downloads file.")
-    output_group.add_argument(
-        "--json", action="store_true",
-        help="Emit machine-readable JSON; suppresses terminal render.")
-    if has_status_line:
-        output_group.add_argument(
-            "--status-line", action="store_true", dest="status_line",
-            help="Emit one-line compact string for status-line injection.")
-
-    parser.add_argument(
-        "--theme", choices=("light", "dark"), default="light",
-        help="Color theme for HTML/SVG (default: light). No-op for markdown.")
-    parser.add_argument(
-        "--no-branding", action="store_true", dest="no_branding",
-        help="Strip the 'Generated by cctally' footer from --format output.")
-    parser.add_argument(
-        "--output", metavar="PATH",
-        help="Write --format output to PATH instead of the default destination "
-             "(stdout for md; ~/Downloads/cctally-<cmd>-<utcdate>.<ext> for html/svg). "
-             "Use '-' for stdout.")
-    parser.add_argument(
-        "--copy", action="store_true",
-        help="Pipe --format md output to clipboard (pbcopy/xclip/clip). "
-             "Rejected for html/svg.")
-    parser.add_argument(
-        "--open", action="store_true", dest="open_after_write",
-        help="After writing --format html/svg to a file, open it in the default app. "
-             "Rejected for md.")
-
-
-def _share_validate_args(args) -> None:
-    """Reject share flag combinations BEFORE any DB / sync / render work.
-
-    Two layers of validation:
-
-    1. Share-only flags (``--output``, ``--copy``, ``--open``) require
-       ``--format``. Silent dropping trains users to assume the file
-       was written.
-
-    2. Destination-shape combinations (``--copy`` + ``--output``,
-       ``--copy`` + non-md, ``--open`` + md, ``--open`` + ``--output -``).
-       These were previously caught only inside ``_resolve_destination``
-       / ``_share_render_and_emit`` — i.e. AFTER ``--sync-current`` had
-       already mutated the DB and the snapshot had been built. Surfacing
-       them at validation time means an exit-2 flag-shape error never
-       triggers side effects.
-
-    Exit 2 with a stderr message naming the offending combo so the
-    failure is loud and scriptable. Idempotent; safe to call from every
-    share-enabled subcommand before the ``--format`` gate. Existing
-    late checks in ``_resolve_destination`` / ``_share_render_and_emit``
-    are kept as defense-in-depth for any future caller that bypasses
-    this helper.
-    """
-    if not getattr(args, "format", None):
-        offenders = []
-        if getattr(args, "output", None):
-            offenders.append("--output")
-        if getattr(args, "copy", False):
-            offenders.append("--copy")
-        if getattr(args, "open_after_write", False):
-            offenders.append("--open")
-        if not offenders:
-            return
-        verb = "requires" if len(offenders) == 1 else "require"
-        sys.stderr.write(
-            f"cctally: {', '.join(offenders)} {verb} --format\n"
-        )
-        sys.exit(2)
-
-    # --format is set — validate destination-shape combos.
-    fmt = args.format
-    copy = getattr(args, "copy", False)
-    output = getattr(args, "output", None)
-    open_after_write = getattr(args, "open_after_write", False)
-
-    if copy and output is not None:
-        # Mutex: a clipboard destination by definition has no path.
-        sys.stderr.write(
-            "cctally: --copy is mutually exclusive with --output\n"
-        )
-        sys.exit(2)
-    if copy and fmt != "md":
-        sys.stderr.write(
-            "cctally: --copy is only valid with --format md\n"
-        )
-        sys.exit(2)
-    if open_after_write and fmt == "md":
-        sys.stderr.write(
-            "cctally: --open is only valid with --format html or --format svg\n"
-        )
-        sys.exit(2)
-    if open_after_write and output == "-":
-        # Open-after-write to stdout has no file to launch — was a silent
-        # no-op pre-fix; now an explicit exit 2 so users notice.
-        sys.stderr.write(
-            "cctally: --open is incompatible with --output - (no file to open)\n"
-        )
-        sys.exit(2)
-
-
-def _build_daily_parser(subparsers, name, *, help_text, xref):
-    """Build the `daily` leaf parser (issue #86 Session B; routes to cmd_daily).
-
-    Build-once, register-twice: this body is the verbatim former inline `daily`
-    construction, parameterized only by `name`, the parent-list `help_text`, and
-    the `xref` appended to `description` (renders on `cctally <name> --help`).
-    """
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show usage grouped by date, matching upstream ccusage daily output."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally daily --since 20260414
-              cctally daily --since 20260410 --until 20260416
-              cctally daily --since 20260414 --breakdown
-              cctally daily --since 20260414 --json
-              cctally daily --order desc
-              cctally daily --instances
-              cctally daily -i --project-aliases repos=Repos
-        """),
-    )
-    p.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    p.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    p.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model cost breakdown sub-rows.",
-    )
-    p.add_argument(
-        "-o", "--order",
-        choices=("asc", "desc"),
-        default="asc",
-        help="Sort direction by date (default: asc).",
-    )
-    p.add_argument(
-        "--reveal-projects",
-        action="store_true",
-        dest="reveal_projects",
-        help="In --format output, show real project basenames instead of "
-             "the default project-1, project-2, ... anonymization.",
-    )
-    p.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    p.add_argument(
-        "-i", "--instances",
-        action="store_true",
-        default=False,
-        help="Group the report by project (git-root).",
-    )
-    p.add_argument(
-        "-p", "--project",
-        action="append",
-        default=None,
-        metavar="PATTERN",
-        help="Filter to projects matching PATTERN (substring of the project "
-             "label or path; repeatable, OR semantics).",
-    )
-    p.add_argument(
-        "--project-aliases",
-        dest="project_aliases",
-        default=None,
-        metavar="PAIRS",
-        help="Comma-separated key=Label pairs overriding project display "
-             "labels (e.g. cctally-dev=Tracker). Display-only.",
-    )
-    _add_ccusage_alias_args(p, ansi_emit=False)
-    _add_mode_arg(p)
-    _add_share_args(p)
-    p.set_defaults(func=cmd_daily)
-    return p
-
-
-def _build_monthly_parser(subparsers, name, *, help_text, xref):
-    """Build the `monthly` leaf parser (issue #86 Session B; routes to cmd_monthly)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show usage grouped by calendar month, matching upstream ccusage monthly output."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally monthly --since 20260101
-              cctally monthly --since 20260101 --until 20260331
-              cctally monthly --since 20260101 --breakdown
-              cctally monthly --since 20260101 --json
-              cctally monthly --order desc
-        """),
-    )
-    p.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    p.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    p.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model cost breakdown sub-rows.",
-    )
-    p.add_argument(
-        "-o", "--order",
-        choices=("asc", "desc"),
-        default="asc",
-        help="Sort direction by month (default: asc).",
-    )
-    p.add_argument(
-        "--reveal-projects",
-        action="store_true",
-        dest="reveal_projects",
-        help="In --format output, show real project basenames instead of "
-             "the default project-1, project-2, ... anonymization.",
-    )
-    p.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    _add_ccusage_alias_args(p, ansi_emit=False)
-    _add_mode_arg(p)
-    _add_share_args(p)
-    p.set_defaults(func=cmd_monthly)
-    return p
-
-
-def _build_weekly_parser(subparsers, name, *, help_text, xref):
-    """Build the `weekly` leaf parser (issue #86 Session B; routes to cmd_weekly)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show Claude usage grouped by subscription week. Boundaries are anchored "
-                    "to weekly_usage_snapshots.week_start_at with 7-day-cadence extrapolation "
-                    "for pre-snapshot history. Columns extend daily/monthly's set with Used % "
-                    "and $/1%."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally weekly
-              cctally weekly --since 20260101
-              cctally weekly --breakdown
-              cctally weekly --json
-              cctally weekly --order desc
-        """),
-    )
-    p.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
-                   help="Filter from date (inclusive).")
-    p.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
-                   help="Filter until date (inclusive).")
-    p.add_argument("-b", "--breakdown", action="store_true",
-                   help="Show per-model cost breakdown sub-rows.")
-    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                   help="Sort direction by week (default: asc).")
-    p.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                   help="In --format output, show real project basenames instead of "
-                        "the default project-1, project-2, ... anonymization.")
-    p.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                   help="Display timezone: local, utc, or IANA name. "
-                        "Overrides config display.tz for this call.")
-    _add_ccusage_alias_args(p, ansi_emit=False)
-    _add_mode_arg(p)
-    _add_share_args(p)
-    p.set_defaults(func=cmd_weekly)
-    return p
-
-
-def _build_session_parser(subparsers, name, *, help_text, xref):
-    """Build the `session` leaf parser (issue #86 Session B; routes to cmd_session)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show Claude usage grouped by JSONL sessionId. Resumed sessions (same "
-                    "sessionId across multiple files) collapse into one row. 11-column "
-                    "layout paralleling codex-session."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally session
-              cctally session --since 20260401
-              cctally session --since 20260401 --breakdown
-              cctally session --json
-              cctally session --order desc
-        """),
-    )
-    p.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
-                   help="Filter from date (inclusive).")
-    p.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
-                   help="Filter until date (inclusive).")
-    p.add_argument("-b", "--breakdown", action="store_true",
-                   help="Show per-model cost breakdown sub-rows.")
-    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                   help="Sort direction by last activity (default: asc — earliest first).")
-    p.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                   help="In --format output, show real project basenames instead of "
-                        "the default project-1, project-2, ... anonymization.")
-    p.add_argument("--top-n", type=int, default=15, dest="top_n",
-                   metavar="N",
-                   help="In --format output, cap rows to top N by cost (default: 15). "
-                        "Must be >= 1; values above 50 emit a readability warning. "
-                        "Has no effect on terminal/JSON output.")
-    p.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                   help="Display timezone: local, utc, or IANA name. "
-                        "Overrides config display.tz for this call.")
-    p.add_argument(
-        "-i", "--id", default=None, metavar="SESSION_ID", dest="id",
-        help="Filter to a single session by exact-string sessionId. "
-             "Match is against the post-resume-merge id (sessions "
-             "resumed across multiple JSONL files collapse to one id). "
-             "Unknown id → exit 0 with the empty-render branch.",
-    )
-    _add_ccusage_alias_args(p, ansi_emit=False)
-    _add_mode_arg(p)
-    _add_share_args(p)
-    p.set_defaults(func=cmd_session)
-    return p
-
-
-def _build_blocks_parser(subparsers, name, *, help_text, xref):
-    """Build the `blocks` leaf parser (issue #86 Session B; routes to cmd_blocks).
-
-    Note: `blocks` intentionally has NO `_add_share_args` (matches the former
-    inline block — it is not part of the shareable-output flag surface).
-    """
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show usage grouped by 5-hour session blocks, matching upstream ccusage blocks output."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally blocks --since 20260414
-              cctally blocks --since 20260410 --until 20260416
-              cctally blocks --since 20260414 --breakdown
-              cctally blocks --since 20260414 --json
-        """),
-    )
-    p.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    p.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    p.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model cost breakdown.",
-    )
-    p.add_argument(
-        "--json",
-        action="store_true",
-        dest="json",
-        help="Output JSON matching upstream ccusage blocks format.",
-    )
-    p.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    p.add_argument(
-        "-a", "--active", action="store_true",
-        help="Show only the active block, with burn-rate + projection "
-             "(ccusage drop-in).",
-    )
-    p.add_argument(
-        "-r", "--recent", action="store_true",
-        help="Show only blocks from the last 3 days (plus the active block).",
-    )
-    p.add_argument(
-        "-t", "--token-limit", dest="token_limit", default=None,
-        metavar="N|max",
-        help="Token limit for the quota %% column / projection warnings. "
-             "An integer, or 'max' (default) to derive from the largest "
-             "completed block.",
-    )
-    p.add_argument(
-        "-n", "--session-length", dest="session_length", type=float,
-        default=5.0, metavar="N",
-        help="Accepted for ccusage drop-in compat; no-op — cctally blocks "
-             "follow Anthropic's real 5-hour resets and are not re-sizable. "
-             "A value <= 0 is rejected.",
-    )
-    _add_ccusage_alias_args(p, ansi_emit=False)
-    _add_mode_arg(p)
-    p.set_defaults(func=cmd_blocks)
-    return p
-
-
-def _build_statusline_parser(subparsers, name, *, help_text, xref):
-    """Build the `statusline` (or `claude statusline`) leaf parser.
-
-    Registered TWICE per the Session B build-once register-twice pattern:
-    once on the flat ``cctally statusline`` subparser, once under the
-    nested ``cctally claude statusline`` subgroup. Output is byte-identical
-    between the two forms; only ``--help`` text differs (the ``xref``
-    paragraph appended to ``description``).
-    """
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description=(
-            "Display a compact one-line status for Claude Code hooks "
-            "(ccusage drop-in + cctally extensions).\n\n" + xref
-        ),
-    )
-    # ccusage-shape flags
-    p.add_argument(
-        "-B", "--visual-burn-rate",
-        dest="visual_burn_rate",
-        default=None,
-        choices=["off", "emoji", "text", "emoji-text"],
-        help="Burn-rate visualization (default: off; config key "
-             "statusline.visual_burn_rate).",
-    )
-    # NOTE: `ccusage` is intentionally NOT in `choices=` so it doesn't
-    # appear in `--help` advertised options. Argparse runs the `choices`
-    # check BEFORE the action's `__call__`, so we cannot list `ccusage`
-    # in `choices=` AND catch it in the action. Instead we omit `choices=`
-    # entirely, manually validate inside the action, and re-raise the
-    # spec's rename hint via `parser.error` for `ccusage` specifically.
-    # Help text below hardcodes the legal set so users still see it in
-    # `--help`. A typo like `ccussage` falls through to a standard
-    # argparse-style "invalid choice" error from `parser.error`.
-    class _CostSourceAction(argparse.Action):
-        _ACCEPTED = ("auto", "cctally", "cc", "both")
-        _RENAMED = "ccusage"
-
-        def __call__(self, parser, namespace, values, option_string=None):
-            if values == self._RENAMED:
-                parser.error(
-                    f"argument {option_string}: invalid choice: "
-                    f"{values!r} — cctally renamed it; try "
-                    f"--cost-source cctally"
-                )
-            if values not in self._ACCEPTED:
-                parser.error(
-                    f"argument {option_string}: invalid choice: "
-                    f"{values!r} (choose from "
-                    + ", ".join(repr(c) for c in self._ACCEPTED)
-                    + ")"
-                )
-            setattr(namespace, self.dest, values)
-
-    p.add_argument(
-        "--cost-source",
-        dest="cost_source",
-        default=None,
-        action=_CostSourceAction,
-        metavar="{auto,cctally,cc,both}",
-        help="Session cost source (default: auto; config key "
-             "statusline.cost_source). Note: 'ccusage' errors with a "
-             "rename hint — use 'cctally' instead.",
-    )
-    p.add_argument(
-        "--cache",
-        dest="cache",
-        action="store_true",
-        default=None,
-        help="Accepted for ccusage drop-in compat; cctally renders from "
-             "cache.db directly without an extra output cache.",
-    )
-    p.add_argument(
-        "--no-cache",
-        dest="cache",
-        action="store_false",
-        help="(no-op alias)",
-    )
-    p.add_argument(
-        "--refresh-interval",
-        dest="refresh_interval",
-        default=1,
-        type=int,
-        metavar="N",
-        help="(no-op alias) Accepted for ccusage drop-in compat.",
-    )
-    p.add_argument(
-        "--context-low-threshold",
-        dest="context_low_threshold",
-        default=50,
-        type=int,
-        metavar="N",
-        help="Below this %% → segment 4 green (default: 50, 0-100).",
-    )
-    p.add_argument(
-        "--context-medium-threshold",
-        dest="context_medium_threshold",
-        default=80,
-        type=int,
-        metavar="N",
-        help="Below this %% → segment 4 yellow; else red (default: 80, 0-100).",
-    )
-    p.add_argument(
-        "-z", "--timezone",
-        dest="timezone",
-        default=None,
-        metavar="TZ",
-        help="Display tz (IANA) for `today` calendar day. Overrides "
-             "display.tz config.",
-    )
-    p.add_argument(
-        "-O", "--offline",
-        dest="offline",
-        action="store_true",
-        default=True,
-        help="(no-op alias) cctally is always offline.",
-    )
-    p.add_argument(
-        "--no-offline",
-        dest="offline",
-        action="store_false",
-        help="(no-op alias)",
-    )
-    p.add_argument(
-        "--color",
-        dest="color",
-        action="store_true",
-        default=None,
-        help="Force ANSI colors on (default: auto via NO_COLOR + TTY).",
-    )
-    p.add_argument(
-        "--no-color",
-        dest="color",
-        action="store_false",
-        help="Force ANSI colors off.",
-    )
-    p.add_argument(
-        "--cctally-extensions",
-        dest="cctally_extensions",
-        action="store_true",
-        default=None,
-        help="Append cctally 5h%%/7d%% segment (default: on; config key "
-             "statusline.cctally_extensions).",
-    )
-    p.add_argument(
-        "--no-cctally-extensions",
-        dest="cctally_extensions",
-        action="store_false",
-        help="Suppress cctally 5h%%/7d%% segment.",
-    )
-    p.add_argument(
-        "--config",
-        dest="config",
-        default=None,
-        metavar="PATH",
-        help="Read config from PATH for this invocation only (no "
-             "mutation of the default config). Missing/invalid PATH "
-             "exits 2.",
-    )
-    p.add_argument(
-        "--single-thread",
-        dest="single_thread",
-        action="store_true",
-        help="(no-op alias) cctally is always single-threaded via the "
-             "session-entry cache.",
-    )
-    p.add_argument(
-        "-d", "--debug",
-        dest="debug",
-        action="store_true",
-        help="Emit pricing-mismatch / config diagnostics on stderr.",
-    )
-    p.set_defaults(func=cmd_statusline, command=name)
-    return p
-
-
-def _build_codex_daily_parser(subparsers, name, *, help_text, xref):
-    """Build the `codex-daily` leaf parser (issue #86 Session B; routes to cmd_codex_daily)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by date, matching upstream ccusage-codex daily output."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-daily --since 20260401
-              cctally codex-daily --since 20260401 --breakdown
-              cctally codex-daily --since 20260401 --json
-              cctally codex-daily --order desc
-        """),
-    )
-    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-b", "--breakdown", action="store_true",
-                   help="Show per-model cost breakdown sub-rows.")
-    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                   help="Sort direction by date (default: asc).")
-    p.add_argument("--json", action="store_true", dest="json",
-                   help="Output JSON matching upstream ccusage-codex daily format.")
-    _add_codex_shared_args(p)
-    p.set_defaults(func=cmd_codex_daily)
-    return p
-
-
-def _build_codex_monthly_parser(subparsers, name, *, help_text, xref):
-    """Build the `codex-monthly` leaf parser (issue #86 Session B; routes to cmd_codex_monthly)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by calendar month, matching upstream ccusage-codex monthly output."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-monthly --since 20260101
-              cctally codex-monthly --breakdown
-              cctally codex-monthly --json
-        """),
-    )
-    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-b", "--breakdown", action="store_true",
-                   help="Show per-model cost breakdown sub-rows.")
-    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                   help="Sort direction by month (default: asc).")
-    p.add_argument("--json", action="store_true", dest="json",
-                   help="Output JSON matching upstream ccusage-codex monthly format.")
-    _add_codex_shared_args(p)
-    p.set_defaults(func=cmd_codex_monthly)
-    return p
-
-
-def _build_codex_weekly_parser(subparsers, name, *, help_text, xref):
-    """Build the `codex-weekly` leaf parser (issue #86 Session B; routes to cmd_codex_weekly)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by week. Week-start day is read from config.json "
-                    "(collector.week_start, Monday default). Not a ccusage-codex drop-in — "
-                    "upstream has no `codex weekly` command."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-weekly
-              cctally codex-weekly --since 20260301
-              cctally codex-weekly --breakdown
-              cctally codex-weekly --json
-              cctally codex-weekly --order desc
-        """),
-    )
-    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-b", "--breakdown", action="store_true",
-                   help="Show per-model cost breakdown sub-rows.")
-    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                   help="Sort direction by week (default: asc).")
-    p.add_argument("--json", action="store_true", dest="json",
-                   help="Output JSON.")
-    _add_codex_shared_args(p)
-    p.set_defaults(func=cmd_codex_weekly)
-    return p
-
-
-def _build_codex_session_parser(subparsers, name, *, help_text, xref):
-    """Build the `codex-session` leaf parser (issue #86 Session B; routes to cmd_codex_session)."""
-    p = subparsers.add_parser(
-        name,
-        help=help_text,
-        formatter_class=CLIHelpFormatter,
-        description="Show Codex usage grouped by session, matching upstream ccusage-codex session output."
-                    "\n\n" + xref,
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally codex-session
-              cctally codex-session --since 20260401
-              cctally codex-session --json
-        """),
-    )
-    p.add_argument("-s", "--since", default=None, metavar="YYYY-MM-DD",
-                   help="Filter from date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-u", "--until", default=None, metavar="YYYY-MM-DD",
-                   help="Filter until date (inclusive; accepts YYYY-MM-DD or YYYYMMDD).")
-    p.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
-                   help="Sort direction by last activity (default: asc — earliest first).")
-    p.add_argument("--json", action="store_true", dest="json",
-                   help="Output JSON matching upstream ccusage-codex session format.")
-    _add_codex_shared_args(p)
-    p.set_defaults(func=cmd_codex_session)
-    return p
-
-
-def build_parser() -> argparse.ArgumentParser:
-    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.
-
-            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.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Quick start:
-              # Add record-usage call to ~/.claude/statusline-command.sh (see record-usage --help)
-              cctally sync-week
-              cctally report
-            """
-        ),
-    )
-    p.add_argument(
-        "-v", "--version",
-        action="store_true",
-        default=argparse.SUPPRESS,
-        help="Print cctally version (from CHANGELOG.md latest release header) and exit",
-    )
-    sub = p.add_subparsers(
-        dest="command",
-        required=False,
-        title="commands",
-        metavar="<command>",
-    )
-
-    py = sub.add_parser(
-        "sync-week",
-        help="Compute weekly cost from session data and store in SQLite",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Compute and store weekly cost (USD) for a selected week window.
-
-            Week selection priority:
-              1) Explicit --week-start/--week-end (date based)
-              2) Latest usage snapshot weekStartAt/weekEndAt (hour-accurate)
-              3) Current week from configured week-start rule
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally sync-week
-              cctally sync-week --week-start 2026-02-05 --week-end 2026-02-12
-              cctally sync-week --mode calculate --offline --json
-            """
-        ),
-    )
-    py.add_argument(
-        "--week-start",
-        default=None,
-        metavar="YYYY-MM-DD",
-        help="Explicit week start date. If --week-end is omitted, uses start + 6 days.",
-    )
-    py.add_argument(
-        "--week-end",
-        default=None,
-        metavar="YYYY-MM-DD",
-        help="Explicit week end date (inclusive date for custom windows).",
-    )
-    py.add_argument(
-        "--week-start-name",
-        default=None,
-        choices=list(WEEKDAY_MAP.keys()),
-        help="Week-start day used when explicit/custom boundaries are not available.",
-    )
-    py.add_argument(
-        "--mode",
-        default="auto",
-        choices=["auto", "calculate", "display"],
-        help="Cost calculation mode: auto, calculate, or display.",
-    )
-    py.add_argument(
-        "--offline",
-        action="store_true",
-        help="Use embedded pricing data (no-op, always used).",
-    )
-    py.add_argument(
-        "--project",
-        default=None,
-        help="Optional project filter for cost calculation.",
-    )
-    py.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit machine-readable JSON output.",
-    )
-    py.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress human-readable output (no effect with --json).",
-    )
-    py.set_defaults(func=cmd_sync_week)
-
-    pr = sub.add_parser(
-        "report",
-        help="Show current and trend dollars-per-1%% statistics",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Report current and historical dollars per 1% weekly usage.
-
-            For each week, report joins:
-              - latest usage snapshot (%)
-              - latest cost snapshot (USD)
-            then computes USD / percent.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally report
-              cctally report --sync-current
-              cctally report --weeks 12 --json
-            """
-        ),
-    )
-    pr.add_argument(
-        "--weeks",
-        type=int,
-        default=8,
-        help="How many recent week windows to include in the trend.",
-    )
-    pr.add_argument(
-        "--sync-current",
-        action="store_true",
-        help="Run sync-week first, then generate the report.",
-    )
-    pr.add_argument(
-        "--week-start-name",
-        default=None,
-        choices=list(WEEKDAY_MAP.keys()),
-        help="Week-start day used if report falls back to date-only week logic.",
-    )
-    pr.add_argument(
-        "--mode",
-        default="auto",
-        choices=["auto", "calculate", "display"],
-        help="Mode passed to sync-week when --sync-current is used.",
-    )
-    pr.add_argument(
-        "--offline",
-        action="store_true",
-        help="Pass --offline to sync-week when --sync-current is used.",
-    )
-    pr.add_argument(
-        "--project",
-        default=None,
-        help="Project filter passed to sync-week when --sync-current is used.",
-    )
-    pr.add_argument(
-        "--reveal-projects",
-        action="store_true",
-        dest="reveal_projects",
-        help="In --format output, show real project basenames instead of "
-             "the default project-1, project-2, ... anonymization.",
-    )
-    pr.add_argument(
-        "--detail",
-        action="store_true",
-        help="Include per-percent cost milestones for the current week.",
-    )
-    pr.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    _add_share_args(pr)
-    pr.set_defaults(func=cmd_report)
-
-    fc = sub.add_parser(
-        "forecast",
-        help="Project current-week usage to reset; show daily budgets",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Forecast end-of-week usage % and daily $ / % budgets to stay under
-            target ceilings (default 100% and 90%). Reads current-week
-            `weekly_usage_snapshots` + `session_entries`; never writes.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally forecast
-              cctally forecast --json
-              cctally forecast --status-line --no-sync
-              cctally forecast --targets 100,95,85
-
-            Status-line integration (add to ~/.claude/statusline-command.sh):
-              forecast_seg=$(cctally forecast --status-line --no-sync 2>/dev/null)
-              # ...then include "$forecast_seg" in your prompt composition.
-            """
-        ),
-    )
-    fc.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                    help="In --format output, show real project basenames instead of "
-                         "the default project-1, project-2, ... anonymization.")
-    fc.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                    help="Display timezone: local, utc, or IANA name. "
-                         "Overrides config display.tz for this call.")
-    fc.add_argument("--targets", default="100,90",
-                    help="Comma-separated integer ceilings (default: 100,90).")
-    fc.add_argument("--explain", action="store_true",
-                    help="Append rationale footer with rate values and source captions.")
-    fc.add_argument("--no-sync", action="store_true", dest="no_sync",
-                    help="Skip sync_cache(); recommended for status-line use.")
-    fc.add_argument("--color", choices=("auto", "always", "never"), default="auto",
-                    help="Color output control (also honors NO_COLOR).")
-    # Dev-only: override "now" for deterministic fixture tests. Hidden from --help.
-    fc.add_argument("--as-of", dest="as_of", default=None, help=argparse.SUPPRESS)
-    _add_share_args(fc, has_status_line=True)
-    fc.set_defaults(func=cmd_forecast)
-
-    # budget — cctally-original (NOT a ccusage drop-in), so flat surface only;
-    # no claude/codex subgroup. `--config` is honored read-only on bare status
-    # but rejected on set/unset (F4). `--reveal-projects` is accepted for share
-    # surface parity but inert (no per-project axis). `--tz` follows the sibling
-    # reporting commands' precedence.
-    bg = sub.add_parser(
-        "budget",
-        help="Weekly equivalent-$ budget + pace + spend alerts",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Track Claude equivalent-$ spend for the current subscription week
-            against a weekly budget. Shows spend, pace, projected end-of-week,
-            and a verdict (ok / warn / over). `budget set <amount>` and
-            `budget unset` manage the budget; spend-crossing alerts fire from
-            record-usage (see `cctally alerts`).
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally budget
-              cctally budget set 300
-              cctally budget unset
-              cctally budget --json
-              cctally budget --format md
-            """
-        ),
-    )
-    bg.add_argument("action", nargs="?", choices=["set", "unset"], default=None,
-                    help="`set <amount>` to set the weekly budget, `unset` to clear it.")
-    bg.add_argument("amount", nargs="?", default=None,
-                    help="Target USD for `budget set` (e.g. 300).")
-    bg.add_argument("--config", default=None,
-                    help="Read status from this config file (read-only; "
-                         "rejected on set/unset).")
-    bg.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                    help="Accepted for --format surface parity; inert for budget "
-                         "(no per-project axis).")
-    bg.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                    help="Display timezone: local, utc, or IANA name. "
-                         "Overrides config display.tz for this call.")
-    _add_share_args(bg)
-    bg.set_defaults(func=cmd_budget)
-
-    pb = sub.add_parser(
-        "percent-breakdown",
-        help="Show per-percent cost milestones for a week",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Show the cumulative and marginal cost at each integer percent threshold
-            for a given week. Milestones are recorded automatically when
-            record-usage stores a snapshot crossing a new integer percent.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally percent-breakdown
-              cctally percent-breakdown --week-start 2026-03-20
-              cctally percent-breakdown --json
-            """
-        ),
-    )
-    pb.add_argument(
-        "--week-start",
-        default=None,
-        metavar="YYYY-MM-DD",
-        help="Week start date. Defaults to the current week.",
-    )
-    pb.add_argument(
-        "--week-start-name",
-        default=None,
-        choices=list(WEEKDAY_MAP.keys()),
-        help="Week-start day used when no explicit date or usage data is available.",
-    )
-    pb.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit machine-readable JSON output.",
-    )
-    pb.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    pb.set_defaults(func=cmd_percent_breakdown)
-
-    fhbd = sub.add_parser(
-        "five-hour-breakdown",
-        help="Per-percent milestones inside one 5h block (mirror of percent-breakdown)",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Show cumulative + marginal cost at each integer percent threshold
-            inside one 5h block. Mirrors percent-breakdown for the 5h axis.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally five-hour-breakdown
-              cctally five-hour-breakdown --block-start 2026-04-30T19:30
-              cctally five-hour-breakdown --ago 1
-              cctally five-hour-breakdown --json
-            """
-        ),
-    )
-    fhbd.add_argument(
-        "--block-start",
-        default=None,
-        metavar="ISO8601",
-        dest="block_start",
-        help="Block start (e.g. 2026-04-30T19:30, naive=UTC).",
-    )
-    fhbd.add_argument(
-        "--ago",
-        default=None,
-        type=int,
-        metavar="N",
-        help="Relative selector: 0=current, 1=previous, etc.",
-    )
-    fhbd.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit camelCase JSON (schemaVersion 1).",
-    )
-    fhbd.add_argument(
-        "--no-color",
-        action="store_true",
-        help="Disable ANSI color output (currently a no-op — table is plain text).",
-    )
-    fhbd.add_argument(
-        "--tz",
-        default=None,
-        type=_argparse_tz,
-        metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    fhbd.set_defaults(func=cmd_five_hour_breakdown)
-
-    tp = sub.add_parser(
-        "tui",
-        help="Live refreshing dashboard (current week, forecast, trend, sessions)",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Live terminal dashboard with four refreshing panels:
-              - Current week % and 5-hour window
-              - Forecast verdict + projections + daily $ budgets
-              - $/1% trend over the last 8 weeks (with sparkline)
-              - Recent Claude sessions (last 100, scrollable)
-
-            Two visual variants — conventional 2x2 grid and expressive
-            hero layout — toggleable at runtime with `v`.
-
-            Requires the `rich` Python package.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally tui
-              cctally tui --expressive
-              cctally tui --refresh 2 --sync-interval 30
-              cctally tui --no-sync
-            """
-        ),
-    )
-    tp.add_argument(
-        "--variant",
-        choices=("conventional", "expressive"),
-        default="conventional",
-        help="Initial layout variant (press 'v' at runtime to toggle).",
-    )
-    tp.add_argument(
-        "--expressive",
-        action="store_const",
-        dest="variant",
-        const="expressive",
-        help="Shortcut for --variant expressive.",
-    )
-    tp.add_argument(
-        "--refresh",
-        type=_tui_refresh_interval_type,
-        default=1.0,
-        metavar="SECONDS",
-        help="UI redraw cadence (default: 1.0).",
-    )
-    tp.add_argument(
-        "--sync-interval",
-        type=_tui_sync_interval_type,
-        default=10.0,
-        metavar="SECONDS",
-        dest="sync_interval",
-        help="Background JSONL sync cadence (default: 10).",
-    )
-    tp.add_argument(
-        "--no-sync",
-        action="store_true",
-        dest="no_sync",
-        help="Disable background sync; render from cache only.",
-    )
-    tp.add_argument(
-        "--no-color",
-        action="store_true",
-        dest="no_color",
-        help="Disable ANSI color (NO_COLOR env var also respected).",
-    )
-    tp.add_argument(
-        "--tz",
-        default=None,
-        type=_argparse_tz,
-        metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    # Dev-only: pin "now" for deterministic fixture tests.
-    tp.add_argument("--as-of", dest="as_of", default=None, help=argparse.SUPPRESS)
-    # Dev-only: fixture injection — render one frame from a Python module that
-    # exposes `SNAPSHOT` (DataSnapshot) and exits.
-    tp.add_argument(
-        "--snapshot-module", dest="snapshot_module", default=None, help=argparse.SUPPRESS
-    )
-    # Dev-only: one-shot render for golden capture.
-    tp.add_argument(
-        "--render-once", action="store_true", dest="render_once", help=argparse.SUPPRESS
-    )
-    # Dev-only: force terminal size for --render-once.
-    tp.add_argument(
-        "--force-size", dest="force_size", default=None, metavar="WxH",
-        help=argparse.SUPPRESS
-    )
-    tp.set_defaults(func=cmd_tui)
-
-    # ---- dashboard subcommand --------------------------------------------
-    dp = sub.add_parser(
-        "dashboard",
-        help="Launch the live web dashboard on http://localhost:8789",
-        description=(
-            "Start a local web server rendering a live dashboard of your "
-            "subscription usage, weekly cost trend, and recent sessions. "
-            "Press Ctrl-C to stop. Two variants are served by the companion "
-            "'tui' subcommand for terminal-only use."
-        ),
-    )
-    dp.add_argument(
-        "--port",
-        type=int,
-        default=8789,
-        help="TCP port to bind (default: 8789).",
-    )
-    dp.add_argument(
-        "--host",
-        default=None,
-        help=("Bind host (default: from config dashboard.bind, fallback "
-              "127.0.0.1 — loopback-only). Use --host 0.0.0.0 to opt in "
-              "to LAN exposure (no auth on /api/* — trusted networks only)."),
-    )
-    dp.add_argument(
-        "--no-browser",
-        action="store_true",
-        help="Skip auto-opening the browser to the dashboard URL.",
-    )
-    dp.add_argument(
-        "--sync-interval",
-        type=_tui_sync_interval_type,  # reuse the TUI validator
-        default=5.0,
-        dest="sync_interval",
-        help="Background snapshot-rebuild cadence in seconds (default: 5).",
-    )
-    dp.add_argument(
-        "--no-sync",
-        action="store_true",
-        dest="no_sync",
-        help="Freeze the snapshot at startup; skip background rebuilds.",
-    )
-    dp.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    dp.set_defaults(func=cmd_dashboard)
-
-    ru = sub.add_parser(
-        "record-usage",
-        help="Record usage data from Claude Code status line",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Record usage percentage from Claude Code status line rate_limits data.
-            Called automatically by the status line script after each assistant message.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally record-usage --percent 14.2 --resets-at 1744531200
-              cctally record-usage --percent 14.2 --resets-at 1744531200 \\
-                --five-hour-percent 38.5 --five-hour-resets-at 1744502400
-
-            Status line integration (add to ~/.claude/statusline-command.sh):
-              if [ -n "$week_pct" ] && [ -n "$week_resets" ]; then
-                  record_args="--percent $week_pct --resets-at ${week_resets%.*}"
-                  if [ -n "$five_pct" ] && [ -n "$five_resets" ]; then
-                      record_args="$record_args --five-hour-percent $five_pct --five-hour-resets-at ${five_resets%.*}"
-                  fi
-                  cctally record-usage $record_args &
-              fi
-            """
-        ),
-    )
-    ru.add_argument(
-        "--percent",
-        required=True,
-        type=float,
-        help="7-day utilization percentage (0-100).",
-    )
-    ru.add_argument(
-        "--resets-at",
-        required=True,
-        help="7-day window reset timestamp (Unix epoch seconds).",
-    )
-    ru.add_argument(
-        "--five-hour-percent",
-        type=float,
-        default=None,
-        help="5-hour utilization percentage (0-100).",
-    )
-    ru.add_argument(
-        "--five-hour-resets-at",
-        default=None,
-        help="5-hour window reset timestamp (Unix epoch seconds).",
-    )
-    ru.set_defaults(func=cmd_record_usage)
-
-    rfu = sub.add_parser(
-        "refresh-usage",
-        help="Force-fetch 7d/5h percent from OAuth API and record it",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Force a fresh fetch of seven_day.utilization and five_hour.utilization
-            from Anthropic's OAuth usage API, persist it via the same path
-            record-usage uses (HWM, percent_milestones, weekly_usage_snapshots),
-            and bust the statusline OAuth cache file at
-            /tmp/claude-statusline-usage-cache.json so the next status-line tick
-            also gets fresh data.
-
-            Use this when the displayed 7d percent is stale (e.g., you've
-            been away from Claude Code and the status-line hasn't fired
-            recently). Otherwise the status-line script handles refresh
-            automatically every minute.
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              ccusage-refresh-usage                  # one-liner output
-              ccusage-refresh-usage --json | jq .    # scriptable
-              ccusage-refresh-usage --quiet          # silent (exit code only)
-
-            Exit codes: 0 success / 2 no OAuth token / 3 network failure
-            / 4 malformed API response / 5 record-usage internal failure.
-            """
-        ),
-    )
-    rfu.add_argument("--json", action="store_true",
-                     help="Emit schema_version=1 JSON to stdout instead of one-liner.")
-    rfu.add_argument("--quiet", action="store_true",
-                     help="Suppress stdout; exit code is the only success signal.")
-    rfu.add_argument("--color", choices=("auto", "always", "never"), default="auto",
-                     help="Color output control (also honors NO_COLOR).")
-    rfu.add_argument("--timeout", type=float, default=5.0,
-                     help="HTTP timeout in seconds (default: 5.0).")
-    rfu.set_defaults(func=cmd_refresh_usage)
-
-    pc = sub.add_parser(
-        "cache-report",
-        help="Show daily cache hit rates per model from ccusage data",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Query ccusage for daily token breakdown and display cache hit
-            percentages per model. Useful for spotting caching regressions
-            after Claude Code updates.
-
-            Cache hit % = cacheReadTokens / (input + cacheCreate + cacheRead)
-            """
-        ),
-        epilog=textwrap.dedent(
-            """\
-            Examples:
-              cctally cache-report
-              cctally cache-report --days 14
-              cctally cache-report --since 2026-04-10 --until 2026-04-18
-              cctally cache-report --by-session --days 14
-              cctally cache-report --by-session --sort cache
-              cctally cache-report --json
-            """
-        ),
-    )
-    pc.add_argument(
-        "--days",
-        type=int,
-        default=7,
-        help="Number of recent days to include.",
-    )
-    pc.add_argument(
-        "--since",
-        default=None,
-        help="Lower window bound (ISO 8601, e.g., '2026-04-10' or "
-             "'2026-04-10T10:00:00Z'). If omitted, falls back to --days.",
-    )
-    pc.add_argument(
-        "--until",
-        default=None,
-        help="Upper window bound (ISO 8601). If omitted, defaults to now.",
-    )
-    pc.add_argument(
-        "--by-session",
-        action="store_true",
-        dest="by_session",
-        help="Group by Claude sessionId (resumed-merged) instead of by date. "
-             "Adds SessionId, Last Activity, and Project identity columns.",
-    )
-    pc.add_argument(
-        "-O", "--offline",
-        action=argparse.BooleanOptionalAction, default=False,
-        help="Use cached pricing data in ccusage. Session A (spec §7.1.2)"
-             " promotes the existing flag to BooleanOptionalAction + -O"
-             " short form so the ccusage drop-in alias surface (-O,"
-             " --offline, --no-offline) all work on cache-report; the"
-             " behavior under each is unchanged (cctally is always"
-             " offline — args.offline still lands as a bool).",
-    )
-    pc.add_argument(
-        "--project",
-        default=None,
-        help="Filter to a specific project.",
-    )
-    pc.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit machine-readable JSON output.",
-    )
-    pc.add_argument(
-        "--anomaly-threshold-pp",
-        type=int,
-        default=15,
-        dest="anomaly_threshold_pp",
-        help="Cache%% drop threshold (percentage points) vs. trailing-median "
-             "baseline for the cache_drop anomaly trigger. Default: 15.",
-    )
-    pc.add_argument(
-        "--anomaly-window-days",
-        type=int,
-        default=14,
-        dest="anomaly_window_days",
-        help="Trailing window (days) for baseline median computation. "
-             "Default: 14.",
-    )
-    pc.add_argument(
-        "--no-anomaly",
-        action="store_true",
-        dest="no_anomaly",
-        help="Disable all anomaly triggers (both cache_drop and net_negative).",
-    )
-    pc.add_argument(
-        "--sort",
-        choices=["date", "net", "cache", "recent", "cost", "anomaly"],
-        default=None,
-        dest="sort",
-        help="Override sort order. Defaults: 'date' in daily mode, 'net' in "
-             "--by-session mode.",
-    )
-    pc.add_argument(
-        "--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    # Session A (spec §7.6): ansi_emit=False; existing `--offline` is
-    # skipped by the helper's `_argparse_has_arg` guard (the collision
-    # case spec §7.1.2 calls out explicitly).
-    _add_ccusage_alias_args(pc, ansi_emit=False)
-    pc.set_defaults(func=cmd_cache_report)
-
-    # -- range-cost --
-    rc = sub.add_parser(
-        "range-cost",
-        help="Compute USD cost for a time range from session data",
-        formatter_class=CLIHelpFormatter,
-        description="Compute USD cost for Claude Code usage between start/end timestamps.",
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally range-cost -s "2026-04-10T10:00:00+03:00"
-              cctally range-cost -s "2026-04-10T10:00:00Z" -e "2026-04-12T10:00:00Z" --breakdown
-              cctally range-cost -s "2026-04-10T10:00:00Z" --json
-              cctally range-cost -s "2026-04-10T10:00:00Z" --total-only
-        """),
-    )
-    rc.add_argument(
-        "-s", "--start",
-        required=True,
-        help="Start timestamp (ISO 8601)",
-    )
-    rc.add_argument(
-        "-e", "--end",
-        default=None,
-        help="End timestamp (ISO 8601, default: now)",
-    )
-    rc.add_argument(
-        "-m", "--mode",
-        default="auto",
-        choices=["auto", "calculate", "display"],
-        help="Cost calculation mode.",
-    )
-    rc.add_argument(
-        "-p", "--project",
-        default=None,
-        help="Filter to a specific project.",
-    )
-    rc.add_argument(
-        "-b", "--breakdown",
-        action="store_true",
-        help="Show per-model usage and cost breakdown.",
-    )
-    rc.add_argument(
-        "--json",
-        action="store_true",
-        dest="json",
-        help="Output JSON.",
-    )
-    rc.add_argument(
-        "--total-only",
-        action="store_true",
-        dest="total_only",
-        help="Print numeric USD total only.",
-    )
-    # Session A (spec §7.6): ansi_emit=False. range-cost has no --tz of
-    # its own (ISO timestamps carry zone info), but the helper-added
-    # -z/--timezone still lands on the namespace; the bridge promotes
-    # it onto args.tz where the rest of the pipeline treats it as a
-    # documented no-op (cmd_range_cost does not consume args.tz).
-    _add_ccusage_alias_args(rc, ansi_emit=False)
-    rc.set_defaults(func=cmd_range_cost)
-
-    # -- blocks --
-    _build_blocks_parser(
-        sub, "blocks",
-        help_text="Show usage report grouped by 5-hour session blocks",
-        xref="Alias of `cctally claude blocks` (the canonical form).")
-
-    # -- statusline --
-    _build_statusline_parser(
-        sub, "statusline",
-        help_text="Compact one-line status for Claude Code hooks",
-        xref="Alias of `cctally claude statusline` (the canonical form).")
-
-    # -- five-hour-blocks --
-    fhb = sub.add_parser(
-        "five-hour-blocks",
-        help="List API-anchored 5h blocks with rollup totals + 7d-drift columns",
-        formatter_class=CLIHelpFormatter,
-        description=(
-            "Show usage grouped by API-anchored 5-hour blocks (analytics view, "
-            "distinct from `cctally blocks` upstream-parity drop-in)."
-        ),
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally five-hour-blocks
-              cctally five-hour-blocks --since 20260420
-              cctally five-hour-blocks --breakdown model
-              cctally five-hour-blocks --breakdown project --json
-        """),
-    )
-    fhb.add_argument(
-        "-s", "--since",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter from date (inclusive).",
-    )
-    fhb.add_argument(
-        "-u", "--until",
-        default=None,
-        metavar="YYYYMMDD",
-        help="Filter until date (inclusive).",
-    )
-    fhb.add_argument(
-        "--breakdown",
-        choices=("model", "project"),
-        default=None,
-        help="Add per-axis rollup-child rows under each block.",
-    )
-    fhb.add_argument(
-        "--reveal-projects",
-        action="store_true",
-        dest="reveal_projects",
-        help="In --format output, show real project basenames instead of "
-             "the default project-1, project-2, ... anonymization.",
-    )
-    fhb.add_argument(
-        "--no-color",
-        action="store_true",
-        help="Accepted for ccusage drop-in compat; this command emits "
-             "plain-text output and no ANSI is suppressed.",
-    )
-    fhb.add_argument(
-        "--tz",
-        default=None,
-        type=_argparse_tz,
-        metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.",
-    )
-    # Session A (spec §7.6 / §7.6.3): ansi_emit=False. fhb already
-    # declares --no-color (refreshed to no-op text in spec §7.6.3); the
-    # helper's --no-color add is short-circuited by the existing-arg
-    # guard. The helper's --color add lands as a parsed-and-ignored
-    # no-op (the renderer emits plain text).
-    _add_ccusage_alias_args(fhb, ansi_emit=False)
-    _add_mode_arg(fhb, noop=True)
-    _add_share_args(fhb)
-    fhb.set_defaults(func=cmd_five_hour_blocks)
-
-    # -- cache-sync --
-    p_cache_sync = sub.add_parser(
-        "cache-sync",
-        help="Sync (or rebuild) the session-entry cache",
-    )
-    p_cache_sync.add_argument(
-        "--rebuild",
-        action="store_true",
-        help="Drop all cached entries and reingest from scratch",
-    )
-    p_cache_sync.add_argument(
-        "--source",
-        choices=("claude", "codex", "all"),
-        default="all",
-        help="Which ingest half to sync/rebuild (default: all).",
-    )
-    p_cache_sync.set_defaults(func=cmd_cache_sync)
-
-    # -- daily --
-    _build_daily_parser(
-        sub, "daily",
-        help_text="Show usage report grouped by date",
-        xref="Alias of `cctally claude daily` (the canonical form).")
-
-    # -- monthly --
-    _build_monthly_parser(
-        sub, "monthly",
-        help_text="Show usage report grouped by month",
-        xref="Alias of `cctally claude monthly` (the canonical form).")
-
-    # -- weekly --
-    _build_weekly_parser(
-        sub, "weekly",
-        help_text="Show usage grouped by subscription week (with Used %% and $/1%%)",
-        xref="Alias of `cctally claude weekly` (the canonical form).")
-
-    # -- codex-daily --
-    _build_codex_daily_parser(
-        sub, "codex-daily",
-        help_text="Show Codex usage report grouped by date (drop-in for `ccusage-codex daily`)",
-        xref="Alias of `cctally codex daily` (the canonical form).")
-
-    # -- codex-monthly --
-    _build_codex_monthly_parser(
-        sub, "codex-monthly",
-        help_text="Show Codex usage grouped by month (drop-in for `ccusage-codex monthly`)",
-        xref="Alias of `cctally codex monthly` (the canonical form).")
-
-    # -- codex-weekly --
-    _build_codex_weekly_parser(
-        sub, "codex-weekly",
-        help_text="Show Codex usage grouped by week (week-start from config.json)",
-        xref="Alias of `cctally codex weekly` (the canonical form).")
-
-    # -- codex-session --
-    _build_codex_session_parser(
-        sub, "codex-session",
-        help_text="Show Codex usage grouped by session (drop-in for `ccusage-codex session`)",
-        xref="Alias of `cctally codex session` (the canonical form).")
-
-    # -- project --
-    p_project = sub.add_parser(
-        "project",
-        help="Roll usage up by project (git-root), with per-project Used %% attribution",
-        formatter_class=CLIHelpFormatter,
-        description=(
-            "Aggregate Claude usage by project (git-root resolved). Default range is "
-            "the current subscription week; use --since/--until or --weeks N to extend."
-        ),
-        epilog=textwrap.dedent("""\
-            Examples:
-              cctally project
-              cctally project --weeks 4
-              cctally project --since 20260401 --until 20260414
-              cctally project --project ccusage --model sonnet
-              cctally project --breakdown --sort used --order desc
-              cctally project --group full-path --json
-        """),
-    )
-    p_project.add_argument("-s", "--since", default=None, metavar="YYYYMMDD",
-                           help="Inclusive start date (YYYY-MM-DD or YYYYMMDD).")
-    p_project.add_argument("-u", "--until", default=None, metavar="YYYYMMDD",
-                           help="Inclusive end date (YYYY-MM-DD or YYYYMMDD).")
-    p_project.add_argument("--weeks", type=int, default=None,
-                           help="Last N subscription weeks ending now.")
-    p_project.add_argument("--project", action="append", default=[], metavar="PATTERN",
-                           help="Substring filter on project display key (repeatable, OR).")
-    p_project.add_argument("--model", action="append", default=[], metavar="PATTERN",
-                           help="Substring filter on model name (repeatable, OR).")
-    p_project.add_argument("-b", "--breakdown", action="store_true",
-                           help="Add per-model child rows under each project.")
-    p_project.add_argument("-o", "--order", choices=("asc", "desc"), default="desc",
-                           help="Sort direction (default: desc).")
-    p_project.add_argument("--sort", choices=("cost", "used", "name", "last-seen"),
-                           default="cost",
-                           help="Sort key (default: cost).")
-    p_project.add_argument("--group", choices=("git-root", "full-path"), default="git-root",
-                           help="Bucket by resolved git-root (default) or raw project_path.")
-    p_project.add_argument("--reveal-projects", action="store_true", dest="reveal_projects",
-                           help="In --format output, show real project basenames instead of "
-                                "the default project-1, project-2, ... anonymization.")
-    p_project.add_argument("--no-color", action="store_true", dest="no_color",
-                           help="Disable ANSI color.")
-    p_project.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-                           help="Display timezone: local, utc, or IANA name. "
-                                "Overrides config display.tz for this call.")
-    # Session A (spec §7.6): ansi_emit=True. project is one of the two
-    # real ANSI emitters. The helper skips its --no-color add (already
-    # declared at p_project above) and adds the new bool --color flag
-    # whose precedence flows through _resolve_color_enabled (§7.3).
-    _add_ccusage_alias_args(p_project, ansi_emit=True)
-    _add_share_args(p_project)
-    p_project.set_defaults(func=cmd_project)
-
-    # -- diff --
-    diff_p = sub.add_parser(
-        "diff",
-        help="Compare Claude usage between two windows.",
-    )
-    diff_p.add_argument("--a", required=True,
-        help="Window A token (this-week | last-week | Nw-ago | this-month | last-month | Nm-ago | last-Nd | prev-Nd | YYYY-MM-DD..YYYY-MM-DD)")
-    diff_p.add_argument("--b", required=True, help="Window B token (same grammar as --a)")
-    diff_p.add_argument("--allow-mismatch", action="store_true",
-        help="Permit mismatched window lengths (deltas normalized per-day)")
-    diff_p.add_argument("--only", help="Comma-separated section list (overall,models,projects,cache)")
-    diff_p.add_argument("--with", dest="with_extra",
-        help="Comma-separated opt-in sections (trend,time)")
-    diff_p.add_argument("--all", dest="show_all", action="store_true",
-        help="Show all rows (bypass noise filter)")
-    diff_p.add_argument("--min-delta", type=float, dest="min_delta_usd",
-        help="Override |Δ$| noise threshold (default 0.10)")
-    diff_p.add_argument("--min-delta-pct", type=float,
-        help="Override |Δ%%| noise threshold (default 1.0)")
-    diff_p.add_argument("--sort",
-        choices=["delta", "cost-a", "cost-b", "name", "status"], default="delta")
-    diff_p.add_argument("--top", type=int, help="Cap rows per section after filter+sort")
-    diff_p.add_argument("--sync", action="store_true",
-        help="Run sync_cache + sync-week before computing")
-    diff_p.add_argument("--tz", default=None, type=_argparse_tz, metavar="TZ",
-        help="Display timezone: local, utc, or IANA name. "
-             "Overrides config display.tz for this call.")
-    diff_p.add_argument("--no-color", action="store_true")
-    diff_p.add_argument("--json", dest="emit_json", action="store_true")
-    diff_p.add_argument("--width", type=int, help=argparse.SUPPRESS)
-    diff_p.add_argument("--debug-now", action="store_true", help=argparse.SUPPRESS)
-    # Session A (spec §7.6): ansi_emit=True. diff is the other real
-    # ANSI emitter. The helper skips its --no-color add (declared
-    # above) and adds the new bool --color flag wired through
-    # _resolve_color_enabled (§7.3). Note: --debug here collides with
-    # diff's existing `--debug-now` (SUPPRESS'd internal flag) but
-    # `--debug-now` is a different option string; the helper still
-    # adds plain `--debug` cleanly.
-    _add_ccusage_alias_args(diff_p, ansi_emit=True)
-    diff_p.set_defaults(func=cmd_diff)
-
-    # -- session --
-    _build_session_parser(
-        sub, "session",
-        help_text="Show Claude usage grouped by sessionId (merges resumed-across-files sessions)",
-        xref="Alias of `cctally claude session` (the canonical form).")
-
-    # --- `claude` subgroup (drop-in for `ccusage claude …`); issue #86 Session B ---
-    # Build-once, register-twice: these reuse the same nine builders as the flat
-    # forms above. Nested subparsers reuse dest="command" so args.command resolves
-    # to the leaf name (e.g. "blocks"), keeping banner suppression byte-identical
-    # to the flat form with zero hook-path changes.
-    claude_p = sub.add_parser(
-        "claude",
-        help="Claude-source reports (drop-in for `ccusage claude …`)",
-        formatter_class=CLIHelpFormatter,
-        description="Claude-source usage reports. Each subcommand is a drop-in for the "
-                    "matching `ccusage claude <cmd>` and shares its engine with the "
-                    "top-level `cctally <cmd>` alias.")
-    claude_sub = claude_p.add_subparsers(dest="command", required=True, metavar="<command>")
-    _build_daily_parser(claude_sub, "daily",
-        help_text="Show usage grouped by date",
-        xref="Drop-in for `ccusage claude daily`. Same engine as `cctally daily`.")
-    _build_monthly_parser(claude_sub, "monthly",
-        help_text="Show usage grouped by month",
-        xref="Drop-in for `ccusage claude monthly`. Same engine as `cctally monthly`.")
-    _build_weekly_parser(claude_sub, "weekly",
-        help_text="Show usage grouped by subscription week",
-        xref="Drop-in for `ccusage claude weekly`. Same engine as `cctally weekly`.")
-    _build_session_parser(claude_sub, "session",
-        help_text="Show usage grouped by session",
-        xref="Drop-in for `ccusage claude session`. Same engine as `cctally session`.")
-    _build_blocks_parser(claude_sub, "blocks",
-        help_text="Show usage grouped by 5-hour session blocks",
-        xref="Drop-in for `ccusage claude blocks`. Same engine as `cctally blocks`.")
-    _build_statusline_parser(claude_sub, "statusline",
-        help_text="Compact one-line status for Claude Code hooks",
-        xref="Canonical `cctally claude statusline` (flat alias: `cctally statusline`). "
-             "Drop-in for `ccusage statusline` plus cctally extension segments.")
-
-    # --- `codex` subgroup (drop-in for `ccusage codex …`); issue #86 Session B ---
-    codex_p = sub.add_parser(
-        "codex",
-        help="Codex-source reports (drop-in for `ccusage codex …`)",
-        formatter_class=CLIHelpFormatter,
-        description="Codex-source usage reports. daily/monthly/session are drop-ins for "
-                    "`ccusage codex <cmd>`; weekly is a cctally extension. Each shares its "
-                    "engine with the matching `cctally codex-<cmd>` alias.")
-    codex_sub = codex_p.add_subparsers(dest="command", required=True, metavar="<command>")
-    _build_codex_daily_parser(codex_sub, "daily",
-        help_text="Show Codex usage grouped by date",
-        xref="Drop-in for `ccusage codex daily`. Same engine as `cctally codex-daily`.")
-    _build_codex_monthly_parser(codex_sub, "monthly",
-        help_text="Show Codex usage grouped by month",
-        xref="Drop-in for `ccusage codex monthly`. Same engine as `cctally codex-monthly`.")
-    _build_codex_session_parser(codex_sub, "session",
-        help_text="Show Codex usage grouped by session",
-        xref="Drop-in for `ccusage codex session`. Same engine as `cctally codex-session`.")
-    _build_codex_weekly_parser(codex_sub, "weekly",
-        help_text="Show Codex usage grouped by week",
-        xref="cctally extension (no upstream `ccusage codex weekly`). Same engine as "
-             "`cctally codex-weekly`.")
-
-    # ---- config (persisted user preferences) ----
-    cfg_p = sub.add_parser(
-        "config",
-        help="Get / set / unset persisted user preferences",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent("""\
-            Manage cctally user preferences in ~/.local/share/cctally/config.json.
-
-            Currently supported keys:
-              display.tz       Display timezone. Values: 'local' (default; host
-                               zone via the OS locale), 'utc', or any IANA name
-                               like 'America/New_York'. Per-call --tz flag on
-                               any subcommand still wins over the persisted value.
-              alerts.enabled   Enable/disable threshold alerts (true/false).
-              dashboard.bind   Host the `dashboard` subcommand binds. Values:
-                               'loopback' (default; binds 127.0.0.1 —
-                               loopback-only), 'lan' (binds 0.0.0.0 —
-                               LAN-accessible), or any literal IP / hostname.
-
-            Examples:
-              cctally config get
-              cctally config get display.tz
-              cctally config set display.tz America/New_York
-              cctally config set dashboard.bind lan
-              cctally config unset dashboard.bind
-        """),
-    )
-    cfg_sub = cfg_p.add_subparsers(dest="action", required=True)
-    cfg_get = cfg_sub.add_parser("get", help="Print current value(s)")
-    cfg_get.add_argument("key", nargs="?", help="Config key (omit to list all)")
-    cfg_get.add_argument("--json", dest="emit_json", action="store_true",
-                         help="Emit JSON instead of key=value lines.")
-    cfg_get.set_defaults(func=cmd_config)
-    cfg_set = cfg_sub.add_parser("set", help="Set a config value")
-    cfg_set.add_argument("key", help="Config key")
-    cfg_set.add_argument("value", help="New value")
-    cfg_set.add_argument("--json", dest="emit_json", action="store_true",
-                         help="Emit JSON instead of key=value confirmation.")
-    cfg_set.set_defaults(func=cmd_config)
-    cfg_unset = cfg_sub.add_parser("unset", help="Remove a config override")
-    cfg_unset.add_argument("key", help="Config key")
-    cfg_unset.set_defaults(func=cmd_config)
-
-    # ---- alerts (threshold-actions Task 6) ----
-    p_alerts = sub.add_parser(
-        "alerts",
-        help="Manage threshold alerts",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent("""\
-            Manage cctally threshold alerts.
-
-            Subcommands:
-              test    Send a synthetic test alert through the dispatch
-                      pipeline (osascript spawn + alerts.log line). Logs
-                      with mode=test so it doesn't pollute real-alert
-                      history.
-
-            Examples:
-              cctally alerts test
-              cctally alerts test --axis five-hour --threshold 95
-        """),
-    )
-    alerts_sub = p_alerts.add_subparsers(dest="alerts_command", required=True)
-    p_alerts_test = alerts_sub.add_parser(
-        "test",
-        help="Send a synthetic test alert through the dispatch pipeline",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent("""\
-            Send a synthetic test alert end-to-end through the alert
-            dispatch pipeline.
-
-            Builds a fake payload using the same content builders the
-            real-alert path uses, then routes through the same osascript
-            spawn and alerts.log writer as production. Distinguishes
-            itself from real threshold-crossing alerts by writing the
-            alerts.log line with mode=test (5th tab-delimited field) —
-            no DB writes, no envelope mutation, so it cannot pollute
-            real-alert history.
-
-            Use this to verify Notification Center delivery is working
-            (osascript present, notifications enabled, no Do Not Disturb)
-            without waiting for a real percent crossing.
-
-            Exit codes:
-              0  alert was queued (osascript spawned successfully)
-              1  osascript missing on this host (not macOS, or binary unavailable)
-              2  --threshold out of [1, 100] range
-              3  other spawn error (PermissionError, OSError, etc.)
-
-            Examples:
-              cctally alerts test
-              cctally alerts test --axis five-hour --threshold 95
-              cctally alerts test --axis budget --threshold 100
-        """),
-    )
-    p_alerts_test.add_argument(
-        "--axis",
-        choices=["weekly", "five-hour", "budget"],
-        default="weekly",
-        help="Alert axis to simulate: weekly subscription window, 5h block, "
-             "or equiv-$ budget (default: weekly).",
-    )
-    p_alerts_test.add_argument(
-        "--threshold",
-        type=int,
-        default=90,
-        help="Threshold percent (1-100, default: 90).",
-    )
-    p_alerts_test.set_defaults(func=cmd_alerts_test)
-
-    # ---- setup (onboarding spec §2) ----
-    sp = sub.add_parser(
-        "setup",
-        help="Install cctally into Claude Code (hooks + symlinks)",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Install cctally into Claude Code by adding hook entries to
-            ~/.claude/settings.json (additive, idempotent) and creating
-            user-facing symlinks under ~/.local/bin/.
-
-            Modes (mutually exclusive):
-              cctally setup                    # install (default)
-              cctally setup --dry-run          # show planned changes, change nothing
-              cctally setup --status           # report current install state
-              cctally setup --uninstall        # remove hooks + symlinks (keep data)
-              cctally setup --uninstall --purge   # also wipe ~/.local/share/cctally/
-            """
-        ),
-    )
-    mode = sp.add_mutually_exclusive_group()
-    mode.add_argument("--status", action="store_true", help="Report current install state")
-    mode.add_argument("--uninstall", action="store_true",
-                      help="Remove hooks + symlinks (keep data unless --purge)")
-    mode.add_argument("--dry-run", action="store_true", dest="dry_run",
-                      help="Show planned changes without modifying anything")
-    sp.add_argument("--purge", action="store_true",
-                    help="With --uninstall: also wipe ~/.local/share/cctally/")
-    sp.add_argument("--yes", "-y", action="store_true",
-                    help="Skip confirmations")
-    sp.add_argument("--json", action="store_true",
-                    help="Emit machine-readable output")
-    sp.add_argument("--force-dev", action="store_true", dest="force_dev",
-                    help="Allow setup to run from a dev checkout (writes "
-                         "dev-pointing hooks into ~/.claude/settings.json)")
-    # Legacy bespoke-hook migration flags (install-mode only — see cmd_setup
-    # post-parse validation). Spec Section 2 mode×flag matrix.
-    mig_group = sp.add_mutually_exclusive_group()
-    mig_group.add_argument(
-        "--migrate-legacy-hooks", action="store_true", dest="migrate_legacy_hooks",
-        help="Auto-accept the legacy-bespoke-hook migration prompt (install only).",
-    )
-    mig_group.add_argument(
-        "--no-migrate-legacy-hooks", action="store_true", dest="no_migrate_legacy_hooks",
-        help="Auto-skip the legacy-bespoke-hook migration prompt (install only).",
-    )
-    sp.set_defaults(func=cmd_setup)
-
-    # ---- db (migration framework — spec §4) ----
-    db_parser = sub.add_parser(
-        "db",
-        help="Migration / DB management (status, skip, unskip)",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Inspect and manage cctally's SQLite migration state.
-
-            Subcommands:
-              status   List migrations + applied/pending/failed/skipped
-                       state across stats.db and cache.db. Glyphs:
-                         ✓ applied   ✗ failed   · pending   ~ skipped
-              skip     Mark a migration as skipped (manual poison-pill
-                       escape — bypass an offending migration).
-              unskip   Remove a skip mark; the migration runs on next
-                       open.
-
-            Migration names accept either bare ("003_…") or qualified
-            ("stats.db:003_…" / "cache.db:003_…") forms. Bare names are
-            rejected with exit 2 if the same NNN_… exists in both
-            registries.
-
-            Examples:
-              cctally db status
-              cctally db status --json
-              cctally db skip 003_merge_5h_block_duplicates_v1 --reason "perf hot"
-              cctally db unskip stats.db:003_merge_5h_block_duplicates_v1
-            """
-        ),
-    )
-    db_sub = db_parser.add_subparsers(dest="db_action", required=True)
-
-    db_status = db_sub.add_parser(
-        "status",
-        help="List migrations + applied/pending/failed/skipped state",
-    )
-    db_status.add_argument(
-        "--json",
-        action="store_true",
-        help="Emit JSON to stdout",
-    )
-    db_status.set_defaults(func=cmd_db_status)
-
-    db_skip = db_sub.add_parser(
-        "skip",
-        help="Mark a migration as skipped",
-    )
-    db_skip.add_argument(
-        "name",
-        help="Migration name (NNN_… or stats.db:NNN_… / cache.db:NNN_…)",
-    )
-    db_skip.add_argument(
-        "--reason",
-        help="Free-text reason (shown in db status)",
-    )
-    db_skip.set_defaults(func=cmd_db_skip)
-
-    db_unskip = db_sub.add_parser(
-        "unskip",
-        help="Remove a skip mark; migration runs on next open",
-    )
-    db_unskip.add_argument(
-        "name",
-        help="Migration name (NNN_… or qualified)",
-    )
-    db_unskip.set_defaults(func=cmd_db_unskip)
-
-    # ─── doctor (Diagnostics) ───────────────────────────────────────────
-    doctor_p = sub.add_parser(
-        "doctor",
-        help="Diagnose data freshness and install state",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Run all read-only diagnostic checks and emit a report.
-
-            Categories: install, hooks, auth, db, data, safety. Each
-            category renders a severity (✓ ok / ⚠ warn / ✗ fail) and
-            actionable remediation guidance for non-OK rows.
-
-            Exit code: 0 unless any check is FAIL (then exit 2). WARN
-            rows do not change the exit code — doctor is a read-only
-            diagnostic and warn-class findings are advisories.
-
-            See docs/commands/doctor.md for the full check inventory
-            and JSON schema reference.
-            """
-        ),
-    )
-    doctor_p.add_argument(
-        "--json", action="store_true",
-        help="Emit machine-readable JSON to stdout (schema_version: 1)",
-    )
-    doctor_mutex = doctor_p.add_mutually_exclusive_group()
-    doctor_mutex.add_argument(
-        "--quiet", "-q", action="store_true",
-        help="Hide OK rows (human mode only)",
-    )
-    doctor_mutex.add_argument(
-        "--verbose", "-v", action="store_true",
-        help="Include each check's details block (human mode only)",
-    )
-    doctor_p.set_defaults(func=cmd_doctor)
-
-    # ---- pricing-check (standalone diagnostic — NOT under claude/codex) ----
-    pc_p = sub.add_parser(
-        "pricing-check",
-        help="Detect stale or missing embedded model pricing",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Check whether cctally's embedded model pricing is stale or
-            missing, across three independently-degrading legs:
-
-              • coverage  (offline, all-history) — models in your cached
-                session data that cctally cannot price (Claude $0) or only
-                approximates (Codex gpt-5 fallback).
-              • drift     (network, LiteLLM) — embedded price values vs the
-                LiteLLM snapshot (direction-aware; allowlist-suppressed).
-              • existence (network, Anthropic /v1/models) — vendor models the
-                API offers that our table lacks. Maintainer-local (needs
-                OAuth); degrades to skipped/degraded otherwise.
-
-            Exit codes:
-              0 — no actionable findings (fully clean, OR partially/fully
-                  network-degraded but nothing actionable; --json still
-                  carries "status":"degraded").
-              1 — any actionable finding (a coverage gap, value drift,
-                  missing-from-us, or an existence gap) — EVEN IF a network
-                  leg degraded. Findings always win over degradation.
-              2 — argument/usage error.
-
-            "status" (ok|degraded) reports check completeness; the exit code
-            reports whether you must act. They are orthogonal.
-
-            See docs/commands/pricing-check.md for the JSON schema.
-            """
-        ),
-    )
-    pc_p.add_argument(
-        "--json", action="store_true",
-        help="Emit machine-readable JSON to stdout (schemaVersion: 1)",
-    )
-    pc_p.add_argument(
-        "--offline", action="store_true",
-        help="Coverage only — skip both network legs (LiteLLM + /v1/models)",
-    )
-    pc_p.set_defaults(func=cmd_pricing_check)
-
-    # `release` is its own standalone entry-point (bin/cctally-release);
-    # no `release` subparser is registered on the main `cctally` CLI.
-    # See docs/RELEASE.md.
-
-    # ---- hook-tick (internal — hidden from --help, see onboarding spec §3) ----
-    ht = sub.add_parser(
-        "hook-tick",
-        help=argparse.SUPPRESS,
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Internal subcommand invoked by Claude Code hooks.
-
-            Reads CC's hook payload from stdin, runs sync_cache, and
-            conditionally refreshes the OAuth usage cache (throttled).
-            Returns 0 unconditionally in normal mode.
-            """
-        ),
-    )
-    ht.add_argument("--explain", action="store_true",
-                    help="Run synchronously, print decision tree, exit informative code")
-    ht.add_argument("--no-oauth", action="store_true",
-                    help="Skip the OAuth refresh entirely (local sync only)")
-    ht.add_argument("--throttle-seconds", type=float, default=None,
-                    help=f"Override throttle (default {int(HOOK_TICK_DEFAULT_THROTTLE_SECONDS)}s)")
-    ht.add_argument("--event", type=str, default=None,
-                    help="Override the event name written to the log line "
-                         "(used by --explain and tests)")
-    ht.add_argument("--mock-oauth-response", type=str, default=None,
-                    help=argparse.SUPPRESS)  # JSON string fed to mock fetch (tests only)
-    ht.set_defaults(func=cmd_hook_tick)
-
-    # ---- update (user-facing self-update subcommand; spec §4) ----
-    sub_update = sub.add_parser(
-        "update",
-        help="Update cctally to the latest version",
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Update cctally to the latest version (npm/brew installs only).
-
-            Modes:
-              cctally update                 install the latest version
-              cctally update --check         show update info without installing
-              cctally update --skip [VER]    don't remind about VER (default: latest)
-              cctally update --remind-later [DAYS]  defer the banner (default: 7)
-            """
-        ),
-    )
-    update_modes = sub_update.add_mutually_exclusive_group()
-    update_modes.add_argument(
-        "--check", action="store_true",
-        help="Show update info without installing",
-    )
-    update_modes.add_argument(
-        "--skip", nargs="?", const=SKIP_USE_STATE_LATEST, metavar="VERSION",
-        default=None,
-        help="Skip a specific version (default: latest in cache)",
-    )
-    update_modes.add_argument(
-        "--remind-later", nargs="?", type=int, const=7, metavar="DAYS",
-        default=None,
-        help="Defer reminders by N days (default: 7)",
-    )
-    # `--version` here is local to the update subparser. The subparser's
-    # value is bound to `args.install_version` (NOT `args.version`) to
-    # avoid a namespace collision with the top-level `--version`
-    # (store_true) flag handled in `main()` before subcommand dispatch:
-    # if both used `dest="version"`, `cctally update --version 1.2.3`
-    # would set `args.version="1.2.3"`, which `main()`'s truthy check
-    # would treat as "global --version requested" and short-circuit to
-    # print the version banner before `cmd_update` ever ran.
-    sub_update.add_argument(
-        "--version", metavar="X.Y.Z", default=None, dest="install_version",
-        help="Install a specific version (npm only; brew has no versioned formulae)",
-    )
-    sub_update.add_argument(
-        "--dry-run", action="store_true",
-        help="Show what would happen, don't install",
-    )
-    sub_update.add_argument(
-        "--force", action="store_true",
-        help="Bypass TTL on --check (force a fresh remote fetch)",
-    )
-    sub_update.add_argument(
-        "--json", action="store_true",
-        help="Emit JSON output (mostly with --check)",
-    )
-    sub_update.set_defaults(func=cmd_update)
-
-    # ---- _update-check (internal — hidden, detached-refresh worker for `cctally update`) ----
-    uc = sub.add_parser(
-        "_update-check",
-        help=argparse.SUPPRESS,
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Internal subcommand: detached version-check worker spawned
-            by `cctally update` (spec §3.6). Touches the throttle
-            marker, fetches the latest version from npm or homebrew
-            depending on install method, and writes update-state.json.
-            Always returns 0; failures are logged to update.log.
-            """
-        ),
-    )
-    uc.set_defaults(func=cmd_update_check_internal)
-
-    # ---- repair-symlinks (internal — hidden; npm-postinstall self-heal, issue #114) ----
-    rs = sub.add_parser(
-        "repair-symlinks",
-        help=argparse.SUPPRESS,
-        formatter_class=CLIHelpFormatter,
-        description=textwrap.dedent(
-            """\
-            Internal subcommand: additively create any missing
-            ~/.local/bin/ symlinks for cctally subcommands (issue #114).
-
-            Invoked best-effort by the npm postinstall on upgrade so new
-            cctally-* binaries become reachable without re-running
-            `cctally setup`. Gated to existing installs (>=1 symlink
-            already present); a fresh install is a silent no-op. Touches
-            only symlinks — no hooks, settings.json, or cache. Refuses
-            from a dev checkout.
-            """
-        ),
-    )
-    rs.set_defaults(func=cmd_repair_symlinks)
-
-    # Python 3.14 leaks `==SUPPRESS==` for hidden subparsers in --help; strip
-    # the pseudo-action so the row disappears entirely. (The choice still
-    # appears in the `{...}` choices header — there's no clean way to hide
-    # that without a custom formatter, and it's harmless.)
-    sub._choices_actions = [
-        a for a in getattr(sub, "_choices_actions", [])
-        if getattr(a, "help", None) is not argparse.SUPPRESS
-    ]
-
-    return p
-
-
-# ============================================================
-# ==== Shareable reports: destination + emit ====            =
-# ============================================================
-# Translate parsed argparse args + a rendered string into actual delivery
-# (stdout / file / clipboard / open). These helpers live here, NOT in
-# `_lib_share.py`, so the kernel module stays I/O-pure (Section 5.8 of the
-# shareable-reports spec).
-
-
-# Module-level latch for the home-dir fallback hint. Spec Section 4.2 calls
-# for a one-shot stderr suggestion when share output lands in $HOME because
-# both XDG_DOWNLOAD_DIR and ~/Downloads were absent. Latched here (process
-# scope) so a user running, e.g., a `cctally daily --format html` followed
-# by `cctally weekly --format html` in the same shell sees the hint exactly
-# once. Tests reset by reaching into the module globals if needed.
-_DOWNLOADS_HOME_HINT_EMITTED = False
-
-
-def _share_resolve_download_dir() -> pathlib.Path:
-    """XDG -> ~/Downloads -> ~ fallback (Section 4.2)."""
-    global _DOWNLOADS_HOME_HINT_EMITTED
-    xdg = os.environ.get("XDG_DOWNLOAD_DIR")
-    if xdg:
-        p = pathlib.Path(xdg).expanduser()
-        if p.exists():
-            return p
-    downloads = pathlib.Path.home() / "Downloads"
-    if downloads.exists():
-        return downloads
-    if not _DOWNLOADS_HOME_HINT_EMITTED:
-        sys.stderr.write(
-            "cctally: writing share output to home dir; "
-            "pass --output <path> to choose a destination\n"
-        )
-        _DOWNLOADS_HOME_HINT_EMITTED = True
-    return pathlib.Path.home()
-
-
-def _share_unique_path(base: pathlib.Path) -> pathlib.Path:
-    """Auto-collision counter — base.html -> base-2.html -> base-3.html -> ... cap 99.
-
-    Exhaustion (>99 same-day collisions) exits 3 per spec Section 4.4. Prior
-    code raised ``SystemExit("…")`` which yields exit 1 — broke the spec's
-    distinct-exit-code contract for collision exhaustion vs. generic errors.
-    """
-    if not base.exists():
-        return base
-    stem = base.stem
-    suffix = base.suffix
-    parent = base.parent
-    for n in range(2, 100):
-        candidate = parent / f"{stem}-{n}{suffix}"
-        if not candidate.exists():
-            return candidate
-    print(
-        f"cctally: too many same-day collisions in {parent}; use --output <path>",
-        file=sys.stderr,
-    )
-    sys.exit(3)
-
-
-def _resolve_destination(
-    args, *, cmd: str, generated_at_utc_date: str
-) -> tuple[str, pathlib.Path | None]:
-    """Translate argparse args into (kind, value).
-
-    kind: "stdout" | "file" | "clipboard"
-    value: pathlib.Path for "file"; None for "stdout" / "clipboard".
-
-    Exit-code contract (spec Section 4.4):
-      - exit 2 on invalid flag combinations (--copy on non-md;
-        --copy + --output; --copy with no clipboard tool; --open + md).
-      - exit 3 on collision exhaustion (delegated to _share_unique_path).
-    """
-    fmt = args.format
-    if getattr(args, "copy", False) and getattr(args, "output", None) is not None:
-        # Mutex: a clipboard destination by definition has no path. Spec
-        # Section 4.4 line 132 calls this out explicitly. Prior code silently
-        # let --copy override --output, which surprised users who expected
-        # the file to land alongside the clipboard write.
-        print(
-            "cctally: --copy is mutually exclusive with --output",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    if getattr(args, "copy", False):
-        if fmt != "md":
-            print("cctally: --copy is only valid with --format md", file=sys.stderr)
-            sys.exit(2)
-        return ("clipboard", None)
-
-    output = getattr(args, "output", None)
-    if output == "-":
-        return ("stdout", None)
-    if output:
-        return ("file", pathlib.Path(output).expanduser())
-
-    if fmt == "md":
-        return ("stdout", None)
-    # html/svg default -> ~/Downloads/cctally-<cmd>-<utcdate>.<ext>
-    base = _share_resolve_download_dir() / f"cctally-{cmd}-{generated_at_utc_date}.{fmt}"
-    return ("file", _share_unique_path(base))
-
-
-def _emit(content: str, *, kind: str, value: pathlib.Path | str | None) -> None:
-    """Deliver rendered content to stdout/file/clipboard."""
-    if kind == "stdout":
-        sys.stdout.write(content)
-        if not content.endswith("\n"):
-            sys.stdout.write("\n")
-        return
-
-    if kind == "file":
-        path = pathlib.Path(value)
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(content, encoding="utf-8")
-        sys.stderr.write(f"Wrote {path}\n")
-        return
-
-    if kind == "clipboard":
-        # Track tools that were found-but-failed separately from "no tool on
-        # PATH" so the error message accurately describes what went wrong.
-        # The prior shape ("requires pbcopy/xclip/clip on PATH") was
-        # misleading when e.g. pbcopy was present but exited non-zero.
-        tried = []
-        for cmd_args in (
-            ["pbcopy"],
-            ["xclip", "-sel", "clip"],
-            ["clip.exe"],
-        ):
-            tool = cmd_args[0]
-            if shutil.which(tool):
-                proc = subprocess.run(cmd_args, input=content, text=True, check=False)
-                if proc.returncode == 0:
-                    sys.stderr.write(f"Copied to clipboard via {tool}\n")
-                    return
-                tried.append(f"{tool} (exit {proc.returncode})")
-        if tried:
-            print(
-                f"cctally: clipboard tool failed: {', '.join(tried)}",
-                file=sys.stderr,
-            )
-            sys.exit(2)
-        print(
-            "cctally: --copy requires pbcopy, xclip, or clip on PATH",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-
-    raise ValueError(f"unknown destination kind: {kind!r}")
-
-
-def _share_load_lib():
-    """Lazy-load `_lib_share` with sys.modules caching.
-
-    Single-load semantics keep ShareSnapshot / MoneyCell / etc. class
-    identities stable across kernel imports: the test harness pre-registers
-    `_lib_share` in `sys.modules`, the wrapper imports it via this helper,
-    and snapshot builders import it via this helper — all paths must see
-    the SAME module object so `isinstance` checks on snapshot cells compare
-    across one class identity, not many. This is the chokepoint for the
-    duplicate-class-identity bug surfaced under the test harness in
-    Implementor 6's fix-loop.
-
-    Registers in sys.modules BEFORE exec_module: Python 3.14's `dataclass`
-    decorator looks up `cls.__module__` in `sys.modules` for `KW_ONLY` type
-    checks, and an absent entry would re-trigger the dual-load path under
-    some import orders.
-    """
-    cached = sys.modules.get("_lib_share")
-    if cached is not None:
-        return cached
-    import importlib.util as _ilu
-    _lib_share_path = pathlib.Path(__file__).resolve().parent / "_lib_share.py"
-    _spec = _ilu.spec_from_file_location("_lib_share", _lib_share_path)
-    _mod = _ilu.module_from_spec(_spec)
-    sys.modules["_lib_share"] = _mod
-    _spec.loader.exec_module(_mod)
-    return _mod
-
-
-def _share_now_utc() -> dt.datetime:
-    """`generated_at` source — honors CCTALLY_AS_OF env hook for fixture stability.
-
-    Mirrors the existing `CCTALLY_AS_OF` precedent used by `project` /
-    `forecast` for deterministic fixture goldens. Format: ISO-8601 with `Z`
-    or explicit offset (e.g. `2026-05-09T12:00:00Z` or
-    `2026-05-09T12:00:00+00:00`); falls back to wall-clock UTC when unset.
-
-    Raises ValueError on malformed `CCTALLY_AS_OF` input — deliberate
-    fail-loud behavior for the dev hook so fixture authors notice typos
-    immediately rather than silently falling back to wall-clock time.
-    """
-    override = os.environ.get("CCTALLY_AS_OF")
-    if override:
-        parsed = dt.datetime.fromisoformat(override.replace("Z", "+00:00"))
-        if parsed.tzinfo is None:
-            parsed = parsed.replace(tzinfo=dt.timezone.utc)
-        return parsed.astimezone(dt.timezone.utc)
-    return dt.datetime.now(dt.timezone.utc)
-
-
-def _share_now_utc_iso() -> str:
-    """`generated_at` ISO-8601 source for /api/share/render snapshot envelopes.
-
-    Honors `CCTALLY_AS_OF` like `_share_now_utc` so fixture goldens stay
-    deterministic across the CLI and HTTP paths. Format `YYYY-MM-DDTHH:MM:SSZ`.
-    """
-    return _share_now_utc().strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-# Spec §11.4 — recent-shares ring buffer caps at 20. Server-side trim
-# in `_handle_share_history_post` so the on-disk `config.json` can't
-# grow unbounded even if a misbehaving client floods POSTs.
-_SHARE_HISTORY_RING_CAP = 20
-
-
-def _share_history_recipe_id() -> str:
-    """Server-stamped opaque id for a history record.
-
-    Random base16 (26 chars / 13 bytes) is sufficient: we order by
-    insertion (ring buffer position), never by id, so we don't need
-    ULID timestamp-prefix monotonicity. `secrets.token_hex` keeps us
-    on stdlib and avoids the predictability of `random`.
-    """
-    import secrets
-    return secrets.token_hex(13)
-
-
-def _share_resolve_version() -> str:
-    """Source from CHANGELOG via the public helper. Empty string if unset.
-
-    `_lib_changelog._read_latest_changelog_version` returns
-    `(version, date) | None`; the snapshot's `version` field carries
-    the version string only.
-    """
-    info = _lib_changelog._read_latest_changelog_version()
-    return info[0] if info else ""
-
-
-def _share_period_label(
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz_label: str,
-) -> str:
-    """Render the canonical "<start> → <end> (<tz>)" period label.
-
-    Used by both the report and daily snapshot builders so the period label
-    format stays consistent across share-enabled subcommands.
-    """
-    return (
-        f"{period_start.strftime('%b %d')} → "
-        f"{period_end.strftime('%b %d')} ({display_tz_label})"
-    )
-
-
-def _share_parse_date_to_dt(value, tz: "ZoneInfo | None") -> dt.datetime:
-    """Coerce a `YYYY-MM-DD` string or `dt.date` into a tz-aware datetime.
-
-    Used by the share gate sites to lift week-boundary date strings
-    (`weekStartDate`, `weekEndDate`) into the tz-aware datetimes that
-    `PeriodSpec` expects. None / empty / unparseable -> current UTC; the
-    caller already gated on a non-empty trend before reaching this path,
-    so the fallback is purely defensive against missing-data corner cases.
-    """
-    if value is None:
-        return _share_now_utc()
-    if isinstance(value, dt.datetime):
-        return value if value.tzinfo else value.replace(tzinfo=tz or dt.timezone.utc)
-    if isinstance(value, dt.date):
-        d = value
-    else:
-        try:
-            d = dt.date.fromisoformat(str(value))
-        except ValueError:
-            return _share_now_utc()
-    midnight = dt.datetime(d.year, d.month, d.day)
-    return midnight.replace(tzinfo=tz or dt.timezone.utc)
-
-
-def _share_display_tz_label(tz: "ZoneInfo | None") -> str:
-    """Render a stable display-tz string for `PeriodSpec.display_tz`.
-
-    `resolve_display_tz` returns `None` for "local" (caller does bare
-    astimezone); the share snapshot needs a non-None string. Map None ->
-    "local" and use ZoneInfo.key otherwise.
-    """
-    return tz.key if tz is not None else "local"
-
-
-def _build_report_snapshot(
-    view: "TrendView",
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally report`.
-
-    Consumes the unified TrendView (spec §6.4). `view.rows` is the
-    chronological (oldest-first) TuiTrendRow tuple — exactly the order
-    the chart needs (BarChart polyline trends left→right with time);
-    no reversal needed.
-
-    The earlier camelCase-dict workaround (recorded in the commit body
-    of Implementor 7 of the share-v2 work) is obsolete: `TuiTrendRow`
-    now carries 10 nullable extended fields (spec §4.1) and is the
-    single typed shape that flows through both CLI report and share
-    builders. Cmd_report's JSON serialization happens at the gate site
-    (camelCase mapping done in cmd_report); this function reads
-    attributes directly from the typed row.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so
-    the builder owns the canonical subtitle shape — no post-build
-    re-stamp at the gate site. The forward-reference return type
-    matches the kernel's lazy-import boundary.
-    """
-    _lib_share = _share_load_lib()
-    columns = (
-        _lib_share.ColumnSpec(key="week", label="Week", align="left"),
-        _lib_share.ColumnSpec(key="used", label="% Used", align="right"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right"),
-        _lib_share.ColumnSpec(key="dpp", label="$ / %", align="right",
-                              emphasis=True),
-    )
-    rows = view.rows  # oldest-first; matches chart's left→right walk.
-    snap_rows: list = []
-    chart_pts: list = []
-    for i, r in enumerate(rows):
-        wsd = r.week_start_date.isoformat() if r.week_start_date else None
-        if isinstance(wsd, str) and wsd:
-            try:
-                week_label = dt.date.fromisoformat(wsd).strftime("%b %d")
-            except ValueError:
-                week_label = wsd
-        else:
-            week_label = "—"
-        # Preserve None vs 0.0 distinction (parity with terminal/JSON).
-        # Terminal _render_weekly_table renders missing values as "—";
-        # share artifact follows the same convention. Coercing None to
-        # 0.0 would render `$0.00` / `0.0%` — indistinguishable from a
-        # genuine zero, and would skew the avg / chart.
-        used_pct_raw = r.used_pct
-        cost_raw = r.weekly_cost_usd
-        dpp_raw = r.dollars_per_percent
-        snap_rows.append(_lib_share.Row(cells={
-            "week": _lib_share.TextCell(week_label),
-            "used": (
-                _lib_share.PercentCell(float(used_pct_raw))
-                if used_pct_raw is not None else _lib_share.TextCell("—")
-            ),
-            "cost": (
-                _lib_share.MoneyCell(float(cost_raw))
-                if cost_raw is not None else _lib_share.TextCell("—")
-            ),
-            "dpp": (
-                _lib_share.MoneyCell(float(dpp_raw))
-                if dpp_raw is not None else _lib_share.TextCell("—")
-            ),
-        }))
-        # Skip chart points for weeks with no $/% sample — the polyline
-        # connects across the gap rather than dropping to 0, which would
-        # misrepresent missing data as a crash to zero.
-        if dpp_raw is not None:
-            chart_pts.append(_lib_share.ChartPoint(
-                x_label=week_label,
-                x_value=float(i),
-                y_value=float(dpp_raw),
-            ))
-    chart = (
-        _lib_share.LineChart(points=tuple(chart_pts), y_label="$ / %")
-        if len(chart_pts) >= 3 else None
-    )
-    # Source the avg from the view (3-sample rule). Falls back to a
-    # length-based average over the chart points for the <3-sample case
-    # so the Totalled cell always renders something concrete; preserves
-    # the prior $0.00 sentinel on empty data.
-    if view.avg_dollars_per_pct is not None:
-        avg_dpp = view.avg_dollars_per_pct
-    else:
-        avg_dpp = (
-            sum(p.y_value for p in chart_pts) / len(chart_pts)
-            if chart_pts else 0.0
-        )
-    totals = (
-        _lib_share.Totalled(label="Avg $/%", value=f"${avg_dpp:,.2f}"),
-    )
-    if rows:
-        title = f"Weekly $ / % trend — last {len(rows)} weeks"
-    else:
-        title = "Weekly $ / % trend — no data"
-    period_label = _share_period_label(period_start, period_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="report",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=(),
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _build_daily_snapshot(
-    view: "DailyView",
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally daily`.
-
-    Consumes the unified DailyView (spec §6.1). `view.aggregated` is
-    the gap-free BucketUsage tuple in newest-first order; we reverse
-    here so BarChart bars render left-to-right chronologically.
-    `view.total_cost_usd` is the pre-computed sum (replacing the
-    prior inline re-totaling).
-
-    Deviations from the plan sketch (which assumed dict rows with keys
-    `date` / `cost_usd` / `pct_of_week` / `top_model`):
-
-    - Rows are `BucketUsage` dataclasses; we read fields by attribute.
-    - Daily has no native `% of week` column — daily is range-scoped, not
-      week-scoped. We render `% of period` (this row's cost / total range
-      cost) so the column carries meaningful info; the `pct_week` key
-      survives in the column spec for plan-shape parity.
-    - `top_model` is the first entry of `model_breakdowns` (sorted by cost
-      desc per upstream ccusage parity); empty → "—".
-
-    `period_start` / `period_end` / `display_tz` are passed by the
-    caller (they reflect the CLI's `--since` / `--until` window which
-    may extend past the data window). `theme` and `reveal_projects`
-    flow into the subtitle directly so the builder owns the canonical
-    subtitle shape — no post-build re-stamp at the gate site.
-    """
-    _lib_share = _share_load_lib()
-    columns = (
-        _lib_share.ColumnSpec(key="date", label="Date", align="left"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right",
-                              emphasis=True),
-        _lib_share.ColumnSpec(key="pct_week", label="% of Period",
-                              align="right"),
-        _lib_share.ColumnSpec(key="top_model", label="Top Model",
-                              align="left"),
-    )
-    # Caller MUST pass rows in chronological order so the BarChart bars
-    # line up left-to-right with time. view.aggregated is newest-first
-    # (matches dashboard convention); reverse for chronological iteration.
-    rows = list(reversed(view.aggregated))
-    total_cost = view.total_cost_usd
-
-    snap_rows: list = []
-    chart_pts: list = []
-    for i, r in enumerate(rows):
-        # `BucketUsage.bucket` is typed `str` (YYYY-MM-DD); guard against
-        # empty / unparseable but skip the dead `dt.date` branch.
-        bucket = getattr(r, "bucket", None)
-        if isinstance(bucket, str) and bucket:
-            try:
-                date_str = dt.date.fromisoformat(bucket).strftime("%b %d")
-            except ValueError:
-                date_str = bucket
-        else:
-            date_str = "—"
-        cost_usd = float(getattr(r, "cost_usd", 0.0) or 0.0)
-        breakdowns = getattr(r, "model_breakdowns", None) or []
-        top_model = (breakdowns[0].get("modelName") if breakdowns else None) or "—"
-        pct_of_period = (cost_usd / total_cost * 100.0) if total_cost > 0 else 0.0
-        snap_rows.append(_lib_share.Row(cells={
-            "date": _lib_share.TextCell(date_str),
-            "cost": _lib_share.MoneyCell(cost_usd),
-            "pct_week": _lib_share.PercentCell(pct_of_period),
-            "top_model": _lib_share.TextCell(top_model),
-        }))
-        chart_pts.append(_lib_share.ChartPoint(
-            x_label=date_str,
-            x_value=float(i),
-            y_value=cost_usd,
-        ))
-    chart = (
-        _lib_share.BarChart(points=tuple(chart_pts), y_label="$")
-        if chart_pts else None
-    )
-    avg_cost = (total_cost / len(chart_pts)) if chart_pts else 0.0
-    totals = (
-        _lib_share.Totalled(label="Sum", value=f"${total_cost:,.2f}"),
-        _lib_share.Totalled(label="Days", value=str(len(chart_pts))),
-        _lib_share.Totalled(label="Avg / day", value=f"${avg_cost:,.2f}"),
-    )
-    if rows:
-        title = (
-            f"Daily usage — {period_start.strftime('%b %d')} → "
-            f"{period_end.strftime('%b %d')}"
-        )
-    else:
-        title = "Daily usage — no data"
-    period_label = _share_period_label(period_start, period_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="daily",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=(),
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _build_monthly_snapshot(
-    view: "MonthlyView",
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally monthly`.
-
-    Consumes the unified MonthlyView (spec §6.2). `view.aggregated` is
-    the gap-free BucketUsage tuple in newest-first order; we reverse
-    so BarChart bars render left-to-right chronologically.
-
-    Deviations from the plan sketch (which assumed dict rows with keys
-    `month` / `cost_usd` / `sessions`):
-
-    - Rows are `BucketUsage` dataclasses; we read fields by attribute.
-    - The plan's `Sessions` column has no source in the underlying data
-      (`BucketUsage` carries no session count and `_aggregate_monthly`
-      never computes one). Substituted with a `Tokens` column carrying
-      total tokens — meaningful info already on the dataclass.
-    - `Δ vs prior` is computed on `cost_usd` between consecutive ASC-sorted
-      months, matching the plan's intent.
-
-    `period_start` / `period_end` / `display_tz` are passed by the
-    caller (the CLI's `--since` / `--until` window may extend past
-    the data window). `theme` / `reveal_projects` flow into the
-    subtitle directly so the builder owns the canonical subtitle
-    shape — no post-build re-stamp at the gate site.
-    """
-    # Caller MUST pass rows in chronological order so the BarChart bars
-    # line up left-to-right with time. view.aggregated is newest-first.
-    rows = list(reversed(view.aggregated))
-    _lib_share = _share_load_lib()
-    columns = (
-        _lib_share.ColumnSpec(key="month", label="Month", align="left"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right",
-                              emphasis=True),
-        _lib_share.ColumnSpec(key="tokens", label="Tokens", align="right"),
-        _lib_share.ColumnSpec(key="delta", label="Δ vs prior", align="right"),
-    )
-    snap_rows: list = []
-    chart_pts: list = []
-    prev_cost: float | None = None
-    for i, r in enumerate(rows):
-        # `BucketUsage.bucket` is typed `str` ("YYYY-MM"); guard against
-        # empty / unparseable but skip the dead `dt.date` branch.
-        bucket = getattr(r, "bucket", None)
-        month_str = bucket if isinstance(bucket, str) and bucket else "—"
-        cost_usd = float(getattr(r, "cost_usd", 0.0) or 0.0)
-        total_tokens = int(getattr(r, "total_tokens", 0) or 0)
-        if prev_cost is not None and prev_cost > 0:
-            delta_pct = (cost_usd - prev_cost) / prev_cost * 100.0
-            delta_cell = _lib_share.DeltaCell(value=delta_pct, unit="%")
-        else:
-            delta_cell = _lib_share.TextCell("—")
-        snap_rows.append(_lib_share.Row(cells={
-            "month": _lib_share.TextCell(month_str),
-            "cost": _lib_share.MoneyCell(cost_usd),
-            "tokens": _lib_share.TextCell(f"{total_tokens:,}"),
-            "delta": delta_cell,
-        }))
-        chart_pts.append(_lib_share.ChartPoint(
-            x_label=month_str,
-            x_value=float(i),
-            y_value=cost_usd,
-        ))
-        prev_cost = cost_usd
-    chart = (
-        _lib_share.BarChart(points=tuple(chart_pts), y_label="$")
-        if chart_pts else None
-    )
-    sum_cost = sum(p.y_value for p in chart_pts)
-    avg_cost = (sum_cost / len(chart_pts)) if chart_pts else 0.0
-    totals = (
-        _lib_share.Totalled(label="Sum", value=f"${sum_cost:,.2f}"),
-        _lib_share.Totalled(label="Months", value=str(len(chart_pts))),
-        _lib_share.Totalled(label="Avg / month", value=f"${avg_cost:,.2f}"),
-    )
-    if rows:
-        title = (
-            f"Monthly usage — {period_start.strftime('%Y-%m')} → "
-            f"{period_end.strftime('%Y-%m')}"
-        )
-    else:
-        title = "Monthly usage — no data"
-    period_label = (
-        f"{period_start.strftime('%Y-%m')} → "
-        f"{period_end.strftime('%Y-%m')} ({display_tz})"
-    )
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="monthly",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=(),
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _build_weekly_snapshot(
-    view: "WeeklyView",
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-    breakdown_model: bool,
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally weekly`.
-
-    Consumes the unified WeeklyView (spec §6.3). `view.aggregated` is
-    the gap-free BucketUsage tuple newest-first; `view.overlay` is the
-    parallel `(used_pct, dollars_per_pct)` tuple. We reverse both for
-    chronological iteration so BarChart bars render left-to-right
-    with time.
-
-    Each bucket carries `bucket` (week_start_date as "YYYY-MM-DD"),
-    `cost_usd`, `total_tokens`, and `model_breakdowns` (list[dict]
-    sorted by cost desc, each `{modelName, ..., cost}`). Either
-    overlay component may be `None` for a week with no captured
-    snapshot — surfaces in the snapshot row as a `0.0` PercentCell so
-    the column stays aligned (matching the table renderer's "no data
-    → 0%" behavior).
-
-    Deviations from the plan sketch (which assumed dict rows with keys
-    `week_start_date` / `used_pct` / `cost_usd` / `sessions` /
-    `model_breakdown` and a `breakdown_model: bool` derived from
-    `args.breakdown == "model"`):
-
-    - Rows are `BucketUsage` dataclasses; per-week `used_pct` lives in the
-      separate `overlay` list — neither shape matches the plan literal.
-    - The plan's `Sessions` column has no source — `BucketUsage` carries
-      no session count and `_aggregate_weekly` never computes one.
-      Substituted with a `Tokens` column (`total_tokens` formatted with
-      thousands separators).
-    - `args.breakdown` for `cmd_weekly` is `action="store_true"` (not a
-      `{model,project}` choice), so `breakdown_model` is just the boolean
-      `args.breakdown` from the gate site.
-    - `model_breakdowns` is a list-of-dicts (`modelName` / `cost`), not a
-      `{model: cost}` mapping; we coerce to a dict before key lookup.
-
-    Honors `breakdown_model` by appending one `m_<model>` column per
-    distinct model and populating `BarChart.stacks` with per-model series.
-    All model-axis iteration uses a single sorted list (`all_model_keys`)
-    so column / stack ordering is deterministic across runs.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so the
-    builder owns the canonical subtitle shape — no post-build re-stamp at
-    the gate site.
-    """
-    # view.aggregated / view.overlay are newest-first; reverse for asc
-    # so BarChart bars are chronological.
-    rows = list(reversed(view.aggregated))
-    overlay = list(reversed(view.overlay))
-    _lib_share = _share_load_lib()
-    columns_list: list = [
-        _lib_share.ColumnSpec(key="week", label="Week Start", align="left"),
-        _lib_share.ColumnSpec(key="used", label="% Used", align="right"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right",
-                              emphasis=True),
-        _lib_share.ColumnSpec(key="tokens", label="Tokens", align="right"),
-    ]
-    # Per-row model→cost lookup (BucketUsage exposes a list-of-dicts;
-    # collapse to dict here so per-row column population is O(1) per
-    # model). All breakdown-aware iteration goes through `all_model_keys`
-    # for deterministic ordering.
-    per_row_model_costs: list[dict[str, float]] = []
-    for r in rows:
-        breakdowns = getattr(r, "model_breakdowns", None) or []
-        per_row_model_costs.append({
-            (b.get("modelName") or "—"): float(b.get("cost") or 0.0)
-            for b in breakdowns
-        })
-    if breakdown_model:
-        all_model_keys = sorted({m for d in per_row_model_costs for m in d})
-        for m in all_model_keys:
-            columns_list.append(_lib_share.ColumnSpec(
-                key=f"m_{m}", label=m, align="right",
-            ))
-    else:
-        all_model_keys = []
-
-    snap_rows: list = []
-    chart_pts: list = []
-    stacks: dict[str, list] = {}
-    for i, r in enumerate(rows):
-        # `BucketUsage.bucket` is typed `str` ("YYYY-MM-DD"); guard against
-        # empty / unparseable but skip the dead `dt.date` branch.
-        bucket = getattr(r, "bucket", None)
-        if isinstance(bucket, str) and bucket:
-            try:
-                week_label = dt.date.fromisoformat(bucket).strftime("%b %d")
-            except ValueError:
-                week_label = bucket
-        else:
-            week_label = "—"
-        cost_usd = float(getattr(r, "cost_usd", 0.0) or 0.0)
-        total_tokens = int(getattr(r, "total_tokens", 0) or 0)
-        # `used_pct` is None when the week lacks a `weekly_usage_snapshots`
-        # row — render as em-dash to match terminal `_render_weekly_table`.
-        # Coercing to 0.0 would conflate "no snapshot recorded" with "0%
-        # used," same divergence the report builder fixes. cost_usd from
-        # session_entries is genuinely 0 when there are no entries (not
-        # missing data) so that path keeps MoneyCell(0.0).
-        used_pct_raw = (
-            overlay[i][0] if i < len(overlay) else None
-        )
-        cells = {
-            "week": _lib_share.TextCell(week_label),
-            "used": (
-                _lib_share.PercentCell(float(used_pct_raw))
-                if used_pct_raw is not None else _lib_share.TextCell("—")
-            ),
-            "cost": _lib_share.MoneyCell(cost_usd),
-            "tokens": _lib_share.TextCell(f"{total_tokens:,}"),
-        }
-        if breakdown_model:
-            row_costs = per_row_model_costs[i]
-            for m in all_model_keys:
-                m_cost = float(row_costs.get(m) or 0.0)
-                cells[f"m_{m}"] = _lib_share.MoneyCell(m_cost)
-                stacks.setdefault(m, []).append(_lib_share.ChartPoint(
-                    x_label=week_label,
-                    x_value=float(i),
-                    y_value=m_cost,
-                    series_key=m,
-                ))
-        snap_rows.append(_lib_share.Row(cells=cells))
-        chart_pts.append(_lib_share.ChartPoint(
-            x_label=week_label,
-            x_value=float(i),
-            y_value=cost_usd,
-        ))
-    # `BarChart.stacks` is `Mapping[str, tuple[ChartPoint, ...]] | None`
-    # (Implementor 1's tightening); convert dict-of-lists to dict-of-tuples.
-    stacks_immut = (
-        {k: tuple(v) for k, v in stacks.items()} if stacks else None
-    )
-    chart = (
-        _lib_share.BarChart(
-            points=tuple(chart_pts), y_label="$", stacks=stacks_immut,
-        )
-        if chart_pts else None
-    )
-    sum_cost = sum(p.y_value for p in chart_pts)
-    pct_values = [
-        float(o[0]) for o in overlay
-        if o is not None and o[0] is not None
-    ]
-    avg_pct = (sum(pct_values) / len(pct_values)) if pct_values else 0.0
-    peak_pct = max(pct_values, default=0.0)
-    totals = (
-        _lib_share.Totalled(label="Sum", value=f"${sum_cost:,.2f}"),
-        _lib_share.Totalled(label="Avg %/wk", value=f"{avg_pct:.1f}%"),
-        _lib_share.Totalled(label="Peak %", value=f"{peak_pct:.1f}%"),
-    )
-    title = (
-        f"Weekly usage — last {len(rows)} weeks"
-        if rows
-        else "Weekly usage — no data"
-    )
-    period_label = _share_period_label(period_start, period_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="weekly",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=tuple(columns_list), rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=(),
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _build_forecast_snapshot(
-    *,
-    week_start: dt.datetime,
-    week_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-    actual_series: list[tuple[str, float, float]],
-    projected_series: list[tuple[str, float, float]],
-    current_pct: float,
-    projected_low_pct: float,
-    projected_high_pct: float,
-    days_remaining: float,
-    dollars_per_percent: float,
-    dollars_per_percent_source: str,
-    low_conf: bool,
-    notes: tuple[str, ...] = (),
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally forecast`.
-
-    `actual_series` is a list of `(x_label, x_value, y_value)` tuples drawn
-    from `weekly_usage_snapshots` for the current week — each sample's
-    `captured_at_utc` is the x_label (formatted compactly), `x_value` is
-    elapsed-hours-since-week-start (a monotonic float so the LineChart
-    renders left→right), and `y_value` is `weekly_percent` at that capture.
-
-    `projected_series` is a parallel list of `(x_label, x_value, y_value)`
-    tuples for the projection ray — the simplest form is a 2-point line
-    from `(now, current_pct)` to `(week_end, projected_eow_pct)`. The
-    renderer treats it as a `multi_series` overlay on top of the actual line.
-
-    Deviations from the plan sketch (which assumed a single
-    `_compute_forecast_data(args) -> dict` helper and `dpp_week_avg` /
-    `dpp_24h` as separate columns):
-
-    - `cmd_forecast` already exposes the data as `ForecastOutput` (which
-      wraps `ForecastInputs`). No helper extraction was needed; we pass
-      the actual scalars in directly.
-    - `ForecastInputs` carries a single `dollars_per_percent` value plus
-      a `dollars_per_percent_source` enum (`this_week` /
-      `trailing_4wk_median` / `this_week_sparse`); there is no separate
-      `dpp_week_avg` and `dpp_24h`. The table renders one $/1% row with
-      the source as a paren suffix in the metric cell.
-    - The plan's single `projected_eow_pct` is split into a low/high
-      range (matching `--render-forecast-terminal`'s "Forecast 80–95%"
-      band). The table shows both ends; the projected_series ray uses
-      the high end so the overlay aligns with the conservative budget
-      consumers expect from the chart.
-
-    Reference lines at 90%/100% are LineChart-stable across all samples;
-    severities `warn` (90%) and `alarm` (100%) drive the renderer's
-    color mapping.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so the
-    builder owns the canonical subtitle shape — no post-build re-stamp
-    at the gate site.
-
-    `notes`, when non-empty, overrides the auto-emitted "LOW CONF — data
-    thin" note. The empty-data fast-path passes a clearer "no snapshots
-    recorded" note so the artifact says what's actually wrong; the
-    confidence-thin terminal path passes nothing and falls back to the
-    auto LOW CONF banner.
-    """
-    _lib_share = _share_load_lib()
-    actual_pts = tuple(
-        _lib_share.ChartPoint(x_label=lbl, x_value=float(xv), y_value=float(yv))
-        for lbl, xv, yv in actual_series
-    )
-    projected_pts = tuple(
-        _lib_share.ChartPoint(x_label=lbl, x_value=float(xv), y_value=float(yv))
-        for lbl, xv, yv in projected_series
-    )
-    chart = (
-        _lib_share.LineChart(
-            points=actual_pts,
-            y_label="cumulative %",
-            reference_lines=(
-                (90.0, "90%", "warn"),
-                (100.0, "100%", "alarm"),
-            ),
-            multi_series={"projected": projected_pts} if projected_pts else None,
-        )
-        if actual_pts else None
-    )
-
-    columns = (
-        _lib_share.ColumnSpec(key="metric", label="Metric", align="left"),
-        _lib_share.ColumnSpec(key="value", label="Value", align="right",
-                              emphasis=True),
-    )
-    # Render the projected band as "low-high%" so a single PercentCell
-    # carries the two-rate forecast spread. When the rates collapse to a
-    # single value (no recent-24h sample), low == high.
-    # 0.05 threshold: below .1f display precision — tighter spreads would
-    # render as identical decimals, so collapse to a single value.
-    if abs(projected_high_pct - projected_low_pct) < 0.05:
-        projected_text = f"{projected_high_pct:.1f}%"
-    else:
-        projected_text = (
-            f"{projected_low_pct:.1f}% — {projected_high_pct:.1f}%"
-        )
-    dpp_source_label = dollars_per_percent_source.replace("_", " ")
-    snap_rows = (
-        _lib_share.Row(cells={
-            "metric": _lib_share.TextCell("Current %"),
-            "value": _lib_share.PercentCell(float(current_pct)),
-        }),
-        _lib_share.Row(cells={
-            "metric": _lib_share.TextCell("Projected end-of-week %"),
-            "value": _lib_share.TextCell(projected_text),
-        }),
-        _lib_share.Row(cells={
-            "metric": _lib_share.TextCell("Days remaining"),
-            "value": _lib_share.TextCell(f"{days_remaining:.1f}"),
-        }),
-        _lib_share.Row(cells={
-            "metric": _lib_share.TextCell(f"$ / 1% ({dpp_source_label})"),
-            "value": _lib_share.MoneyCell(float(dollars_per_percent)),
-        }),
-    )
-    # Caller-provided `notes` (e.g., empty-data path's clearer message)
-    # take precedence over the auto LOW CONF banner. Sibling builders
-    # don't expose this knob; forecast does because its empty-state and
-    # thin-confidence states need different copy.
-    final_notes = notes if notes else (
-        ("LOW CONF — data thin",) if low_conf else ()
-    )
-    if actual_pts:
-        title = f"Forecast — week of {week_start.strftime('%b %d')}"
-    else:
-        title = "Forecast — no data"
-    # Reuse the shared period-label helper so forecast's subtitle period
-    # format matches sibling builders (cmd_daily / cmd_project / etc.).
-    period_label = _share_period_label(week_start, week_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="forecast",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=week_start, end=week_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=snap_rows,
-        chart=chart, totals=(), notes=final_notes,
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _build_project_snapshot(
-    rows: list[dict],
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally project`.
-
-    `rows` is the in-memory per-project aggregate list produced inside
-    `cmd_project` (`project_rows.values()` post-sort). Each row is a
-    dict with: `key` (a `ProjectKey` carrying `display_key` /
-    `bucket_path`), `cost_usd`, `attributed_pct` (`float | None`),
-    `sessions` (a `set` of session-IDs).
-
-    Privacy invariant (Section 8.4 / Section 5.3): the builder populates
-    `ProjectCell.label` AND `ChartPoint.project_label` (and `x_label`,
-    which is the project axis on a HorizontalBarChart) with the REAL
-    `display_key`. The `_share_render_and_emit` wrapper then runs
-    `_lib_share._scrub` BEFORE rendering — that's the single chokepoint
-    that rewrites every project label to `project-1` / `project-2` /
-    ... unless `--reveal-projects` is passed. The Section 8.4 canary
-    test (`test_anonymized_output_contains_zero_original_tokens`) and
-    the wrapper-level regression
-    (`test_share_render_and_emit_scrubs_project_labels`) both anchor
-    this contract.
-
-    Deviations from the plan sketch (which assumed dict rows with keys
-    `project` / `cost_usd` / `used_pct` / `sessions`):
-
-    - Rows are dicts whose `key` field is a `ProjectKey` dataclass; the
-      project label comes from `key.display_key`. The plan's `project`
-      key does not exist on the actual `cmd_project` data shape.
-    - `attributed_pct` may be `None` for projects whose contributing
-      weeks all lacked a `weekly_usage_snapshots` row; the table renders
-      that as em-dash (parity with terminal `_render_project_table`).
-    - Sessions is a `set`; the cell carries its `len(...)` as text.
-
-    `HorizontalBarChart.cap=12` matches the plan; when more than 12
-    projects exist, a note clarifies that the table includes all rows
-    while the chart shows only the top 12 by cost.
-
-    Caller MUST pass `rows` already sorted in the desired order
-    (cmd_project honors `--sort` / `--order` upstream). The builder
-    preserves caller order for the table — terminal / JSON / share
-    artifacts all show the same row ordering. Internally the builder
-    ALSO computes a descending-cost copy that drives the HBar chart
-    and the basename-disambiguation rank (both must match
-    `_build_anon_mapping`'s descending-cost sort so `project-1` stays
-    glued to the highest-cost bar regardless of `--sort`). Anonymization
-    is row-identity based (`id(r)` → augmented label), not position
-    based, so the table sees the same disambiguated label as the chart.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so the
-    builder owns the canonical subtitle shape — no post-build re-stamp
-    at the gate site.
-    """
-    _lib_share = _share_load_lib()
-    columns = (
-        _lib_share.ColumnSpec(key="project", label="Project", align="left"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right",
-                              emphasis=True),
-        _lib_share.ColumnSpec(key="used", label="% Used", align="right"),
-        _lib_share.ColumnSpec(key="sessions", label="Sessions", align="right"),
-    )
-    # Two orderings — same rows, different consumers:
-    #
-    # * `rows` (caller order) drives the table. `cmd_project` upstream
-    #   has already applied `--sort` / `--order`, so the share artifact's
-    #   table matches terminal / JSON output for any of `--sort cost`,
-    #   `--sort name`, `--sort sessions` × `--order asc|desc`.
-    #
-    # * `cost_sorted_rows` (descending cost) drives the HBar chart and
-    #   the basename-disambiguation rank — both must align with
-    #   `_build_anon_mapping`'s descending-cost sort so `project-1` stays
-    #   glued to the highest-cost bar regardless of `--sort` choice.
-    cost_sorted_rows = sorted(
-        rows, key=lambda r: -float(r.get("cost_usd") or 0.0)
-    )
-    # Basename-collision disambiguation: mirrors `_render_project_table`'s
-    # terminal logic. Computed on cost_sorted_rows; mapped back to row
-    # identity so the caller-ordered table picks up the same augmented
-    # label as the chart (anonymization is row-identity based, not
-    # position based). Without disambiguation, two `app` projects under
-    # different parent dirs collapse to ONE anonymous `project-N` after
-    # scrub — losing both privacy uniqueness and chart rank meaning.
-    augmented_by_index = _project_disambiguate_labels(cost_sorted_rows)
-    augmented_by_row_id: dict[int, str] = {
-        id(cost_sorted_rows[idx]): label
-        for idx, label in augmented_by_index.items()
-    }
-
-    def _proj_label_for(r: dict) -> str:
-        bare = getattr(r.get("key"), "display_key", None) or "(unknown)"
-        return augmented_by_row_id.get(id(r), bare)
-
-    # Table rows in CALLER order (--sort / --order parity).
-    snap_rows: list = []
-    for r in rows:
-        proj_label = _proj_label_for(r)
-        cost = float(r.get("cost_usd") or 0.0)
-        attr_pct = r.get("attributed_pct")
-        sessions = r.get("sessions")
-        sessions_count = len(sessions) if sessions is not None else 0
-        snap_rows.append(_lib_share.Row(cells={
-            "project": _lib_share.ProjectCell(proj_label),
-            "cost": _lib_share.MoneyCell(cost),
-            # Preserve None vs 0.0 — terminal renders missing as em-dash.
-            # Coercing None -> 0.0 would conflate "no usage snapshot for
-            # any week this project touched" with "0% attributed."
-            "used": (
-                _lib_share.PercentCell(float(attr_pct))
-                if attr_pct is not None else _lib_share.TextCell("—")
-            ),
-            "sessions": _lib_share.TextCell(str(sessions_count)),
-        }))
-
-    # Chart points in COST-SORTED order (HBar shows top-N by cost).
-    chart_pts: list = []
-    for r in cost_sorted_rows:
-        proj_label = _proj_label_for(r)
-        cost = float(r.get("cost_usd") or 0.0)
-        chart_pts.append(_lib_share.ChartPoint(
-            x_label=proj_label,
-            x_value=cost,
-            y_value=cost,
-            project_label=proj_label,
-        ))
-    chart = (
-        _lib_share.HorizontalBarChart(
-            points=tuple(chart_pts), x_label="$", cap=12,
-        )
-        if chart_pts else None
-    )
-    notes: tuple[str, ...] = ()
-    if chart is not None and len(chart_pts) > 12:
-        notes = (
-            f"Showing top 12 in chart; table includes all {len(chart_pts)}.",
-        )
-    sum_cost = sum(p.y_value for p in chart_pts)
-    totals = (
-        _lib_share.Totalled(label="Sum", value=f"${sum_cost:,.2f}"),
-        _lib_share.Totalled(label="Projects", value=str(len(chart_pts))),
-    )
-    if rows:
-        title = (
-            f"Per-project usage — {period_start.strftime('%b %d')} → "
-            f"{period_end.strftime('%b %d')}"
-        )
-    else:
-        title = "Per-project usage — no data"
-    period_label = _share_period_label(period_start, period_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="project",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=notes,
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _build_five_hour_blocks_snapshot(
-    view: "BlocksView",
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-    tz: "ZoneInfo | None",
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally five-hour-blocks`.
-
-    `view` is the ``BlocksView`` produced by
-    ``build_blocks_view_from_table_rows`` (issue #56). The
-    API-anchored block dicts (sqlite Row → dict with the
-    ``__is_active`` / ``__credits`` side-channels attached) live on
-    ``view.aggregated``; reset-aware totals come from
-    ``view.total_cost_usd`` so the share footer reads from the typed
-    single source rather than re-summing inline. Schema fields used
-    from each dict: ``block_start_at`` (ISO timestamp),
-    ``total_cost_usd``, ``final_five_hour_percent``,
-    ``crossed_seven_day_reset`` (0/1 int),
-    ``seven_day_pct_at_block_start``, ``seven_day_pct_at_block_end``,
-    plus the synthetic ``__is_active`` flag.
-
-    Deviations from the plan sketch (which assumed dict rows with keys
-    `block_start` / `cost_usd` / `used_pct_5h` / `top_model` /
-    `cross_reset`):
-
-    - Rows are sqlite-Row-derived dicts with snake_case schema column
-      names — `block_start_at`, `total_cost_usd`,
-      `final_five_hour_percent`, `crossed_seven_day_reset`. The plan
-      keys `block_start` / `cost_usd` / `used_pct_5h` / `cross_reset`
-      do not exist on the actual data shape.
-    - `top_model` does not live on the `five_hour_blocks` row at all;
-      `_load_breakdown` would have to be invoked per-block to derive
-      it. Per share-spec convention (matches cmd_daily / cmd_monthly),
-      the `--breakdown` flag is a no-op under `--format` and the
-      headline snapshot omits the per-model "top model" column.
-    - `crossed_seven_day_reset` is an INTEGER 0/1 (sqlite); coerce to
-      `bool` for cell formatting.
-
-    Cross-reset markers (spec §6.5):
-      - `chart_pts` — `▲` (U+25B2) prefix in `x_label` so the SVG
-        x-axis label visually flags the crossed-reset blocks.
-      - `snap_rows` — `⚡` (U+26A1) glyph in the `cross_reset` cell
-        text so the markdown / HTML table cell carries the same
-        signal. The two glyphs are distinct (triangle for chart axis,
-        bolt for table cell) so the legend reads correctly in either
-        surface.
-
-    `theme` and `reveal_projects` flow into the subtitle directly so
-    the builder owns the canonical subtitle shape — no post-build
-    re-stamp at the gate site.
-
-    Caller MUST pass a view whose ``aggregated`` block dicts are
-    already in the desired chronological order (cmd_five_hour_blocks
-    pulls newest-first; we reverse here so the BarChart bars line up
-    oldest→newest left-to-right). Tabular row order in the snapshot is
-    irrelevant because the snapshot is what gets rendered (the gate
-    site short-circuits the table renderer).
-    """
-    _lib_share = _share_load_lib()
-    columns = (
-        _lib_share.ColumnSpec(key="block_start", label="Block Start",
-                              align="left"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right",
-                              emphasis=True),
-        _lib_share.ColumnSpec(key="used_pct", label="5h %",
-                              align="right"),
-        _lib_share.ColumnSpec(key="cross_reset", label="Reset",
-                              align="left"),
-    )
-    # `view.aggregated` carries the newest-first DESC block dicts the
-    # caller built from the SELECT. Reverse so BarChart x-axis runs
-    # oldest→newest; table-row order tracks chart order so consumer
-    # expectations align.
-    rows = list(view.aggregated)
-    chrono_rows = list(reversed(rows))
-    snap_rows: list = []
-    chart_pts: list = []
-    for i, r in enumerate(chrono_rows):
-        block_iso = r.get("block_start_at") or ""
-        # Compact label respecting --tz; previously hard-coded to UTC
-        # (parsed.strftime renders the wall-clock IN the parsed tz, and
-        # `parsed` is tz-aware UTC after fromisoformat). UTC-vs-display_tz
-        # is orthogonal to the SVG x-axis width budget — both render at
-        # the same character count. Route through `format_display_dt`
-        # with suffix=False to satisfy the chokepoint rule while keeping
-        # the bar label compact (the subtitle's period_label already
-        # carries the active tz).
-        try:
-            parsed = dt.datetime.fromisoformat(
-                block_iso.replace("Z", "+00:00")
-            )
-            block_lbl = format_display_dt(
-                parsed, tz, fmt="%b %d %H:%M", suffix=False,
-            )
-        except (ValueError, AttributeError):
-            block_lbl = str(block_iso)
-        cost_usd = float(r.get("total_cost_usd") or 0.0)
-        used_pct = float(r.get("final_five_hour_percent") or 0.0)
-        crossed = bool(r.get("crossed_seven_day_reset"))
-        cell_text = "⚡" if crossed else "—"
-        # Spec §5.1.1 (Codex r2 finding 3): consume the ``__credits``
-        # side-channel set by ``cmd_five_hour_blocks`` and append a
-        # ``⚡ -Xpp, -Ypp`` chip to the block_start cell. Pure-string
-        # cell content flows uniformly through markdown / HTML table /
-        # SVG text renderers without per-format additions. Symmetric to
-        # the existing ⚡ glyph in the cross_reset cell — by position
-        # (block_start suffix vs. dedicated column) the two annotations
-        # remain visually distinguishable.
-        credits = r.get("__credits") or []
-        block_cell = block_lbl
-        if credits:
-            deltas = ", ".join(f"{c['deltaPp']:+.0f}pp" for c in credits)
-            block_cell = f"{block_lbl} ⚡ {deltas}"
-        snap_rows.append(_lib_share.Row(cells={
-            "block_start": _lib_share.TextCell(block_cell),
-            "cost": _lib_share.MoneyCell(cost_usd),
-            "used_pct": _lib_share.PercentCell(used_pct),
-            "cross_reset": _lib_share.TextCell(cell_text),
-        }))
-        x_label = f"▲ {block_lbl}" if crossed else block_lbl
-        chart_pts.append(_lib_share.ChartPoint(
-            x_label=x_label,
-            x_value=float(i),
-            y_value=cost_usd,
-        ))
-    chart = (
-        _lib_share.BarChart(points=tuple(chart_pts), y_label="$")
-        if chart_pts else None
-    )
-    # Reset-aware total comes from the BlocksView (issue #56); avg
-    # divides by `chart_pts` count so the share footer "Sum" totalled
-    # and the per-block `chart_pts` cost values share a single source-
-    # of-truth at `view.total_cost_usd`.
-    sum_cost = view.total_cost_usd
-    avg_cost = (sum_cost / len(chart_pts)) if chart_pts else 0.0
-    crossed_count = sum(
-        1 for r in chrono_rows if bool(r.get("crossed_seven_day_reset"))
-    )
-    totals_list = [
-        _lib_share.Totalled(label="Sum", value=f"${sum_cost:,.2f}"),
-        _lib_share.Totalled(label="Blocks", value=str(len(chart_pts))),
-        _lib_share.Totalled(label="Avg / block", value=f"${avg_cost:,.2f}"),
-    ]
-    if crossed_count:
-        totals_list.append(_lib_share.Totalled(
-            label="Crossed reset", value=str(crossed_count),
-        ))
-    totals = tuple(totals_list)
-    notes: tuple[str, ...] = ()
-    if crossed_count:
-        notes = (
-            "▲ / ⚡ marks blocks that crossed the weekly reset boundary.",
-        )
-    if rows:
-        title = f"5-hour blocks — last {len(rows)} blocks"
-    else:
-        title = "5-hour blocks — no data"
-    period_label = _share_period_label(period_start, period_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="five-hour-blocks",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=notes,
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-def _session_disambiguate_labels(
-    sessions: list["ClaudeSessionUsage"],
-) -> dict[int, str]:
-    """Return ``{session_index: disambiguated_label}`` for sessions whose
-    bare ``project_path`` basename collides with another session's.
-
-    Session-specific sibling of ``_project_disambiguate_labels`` (which
-    operates over project rollup rows whose `key` is a ``ProjectKey``).
-    Sessions carry only a `project_path` string — we derive the
-    basename, count collisions, and append a parent-dir suffix
-    ``" (parent)"`` to colliding rows so the post-scrub anonymization
-    still produces unique anonymous labels (otherwise two `app/`
-    sessions under different parents collapse to a single
-    ``project-N``, breaking both privacy uniqueness and the chart's
-    visual rank meaning).
-
-    Sessions without collisions are absent from the returned dict;
-    callers fall back to the bare basename.
-    """
-    basenames: list[str] = []
-    for s in sessions:
-        path = s.project_path or ""
-        basenames.append(os.path.basename(path) or path or "(unknown)")
-    counts: dict[str, int] = {}
-    for bn in basenames:
-        counts[bn] = counts.get(bn, 0) + 1
-    augmented: dict[int, str] = {}
-    for idx, s in enumerate(sessions):
-        bn = basenames[idx]
-        # Skip suffixing the literal "(unknown)" bare label even on
-        # collision: `_build_anon_mapping` literal-passthrough-protects
-        # exact "(unknown)" only — a suffixed form like "(unknown) (/)"
-        # would be mapped to a regular `project-N` slot, losing the
-        # (unknown) semantic in the anonymized output.
-        if counts[bn] > 1 and bn != "(unknown)":
-            path = s.project_path or ""
-            parent = os.path.basename(os.path.dirname(path)) or "/"
-            augmented[idx] = f"{bn} ({parent})"
-    return augmented
-
-
-def _build_session_snapshot(
-    view: "SessionsView",
-    *,
-    period_start: dt.datetime,
-    period_end: dt.datetime,
-    display_tz: str,
-    version: str,
-    theme: str,
-    reveal_projects: bool,
-    top_n: int | None,
-    tz: "ZoneInfo | None",
-) -> "ShareSnapshot":
-    """Build a ShareSnapshot for `cctally session`.
-
-    Consumes the unified ``SessionsView`` (spec §6.5). ``view.aggregated``
-    is the ``ClaudeSessionUsage`` tuple — the shape this builder needs
-    for ``source_paths`` / ``model_breakdowns`` / ``last_activity``
-    (fields ``view.rows`` / ``TuiSessionRow`` doesn't carry). The
-    in-memory shape is unchanged at the read boundary — only the
-    parameter container differs.
-
-    Each ``ClaudeSessionUsage`` has: ``session_id`` (UUID),
-    ``project_path`` (filesystem path), ``cost_usd``,
-    ``last_activity`` (``dt.datetime``), ``models`` (first-seen-order
-    ``list[str]``), and the token aggregates.
-
-    Privacy invariant (Section 8.4 / Section 5.3): the builder populates
-    `ProjectCell.label`, `ChartPoint.project_label`, and
-    `ChartPoint.x_label` with the REAL `project_path` basename. The
-    `_share_render_and_emit` wrapper runs `_lib_share._scrub` BEFORE
-    rendering — that's the single chokepoint that rewrites every
-    project label to `project-1` / `project-2` / ... unless
-    `--reveal-projects` is passed.
-
-    Deviations from the plan sketch (which assumed dict rows with keys
-    `session_id` / `started_at` / `project_path` / `cost_usd` /
-    `models`):
-
-    - Sessions are `ClaudeSessionUsage` dataclasses; we read fields by
-      attribute. `last_activity` is the canonical timestamp (no
-      `started_at` field — sessions span a window via
-      `first_activity` → `last_activity`).
-    - The `project_path` column's basename can collide across two
-      different parent dirs. We use the session-specific
-      `_session_disambiguate_labels` helper (sibling of
-      `_project_disambiguate_labels`, which expects `ProjectKey` rows
-      not present on session data) to suffix `" (parent)"` on
-      collisions before the scrubber runs.
-
-    Caller MUST pass ``view`` whose ``aggregated`` tuple is already
-    sorted in the desired order (``cmd_session`` keeps the
-    aggregator's descending-by-last_activity sort); the builder
-    re-sorts internally by descending cost so the chart's HBar bars
-    rank consistently with the anonymization-mapping
-    (``_build_anon_mapping`` also sorts by descending cost) — keeping
-    ``project-1`` aligned with the highest-cost bar in the chart even
-    when the user asked for ``--order asc``.
-
-    `top_n`, when set (must be `>= 1`; caller validates), truncates
-    BOTH the table rows and the chart points to the top-N by cost.
-    The title shifts to `"Top N sessions"` whenever `top_n` actually
-    truncated (so users know rows were dropped). When more rows exist
-    than the chart cap (15) but `top_n` is None or `>= len(sessions)`,
-    the table includes all rows while the chart shows the top 15 by
-    cost (a note clarifies).
-
-    `theme` and `reveal_projects` flow into the subtitle directly so
-    the builder owns the canonical subtitle shape — no post-build
-    re-stamp at the gate site.
-    """
-    _lib_share = _share_load_lib()
-    columns = (
-        _lib_share.ColumnSpec(key="session", label="Session", align="left"),
-        _lib_share.ColumnSpec(key="project", label="Project", align="left"),
-        _lib_share.ColumnSpec(key="cost", label="$ Cost", align="right",
-                              emphasis=True),
-        _lib_share.ColumnSpec(key="last_activity", label="Last Activity",
-                              align="left"),
-        _lib_share.ColumnSpec(key="models", label="Models", align="left"),
-    )
-    # Sort by descending cost so the snapshot's chart-order matches the
-    # `_build_anon_mapping` sort key (also descending cost).
-    sorted_sessions = sorted(
-        view.aggregated,
-        key=lambda s: -float(getattr(s, "cost_usd", 0.0) or 0.0),
-    )
-    # Apply --top-n truncation (caller validated >= 1). Truncation status
-    # gates the title shape below.
-    truncated = (
-        top_n is not None and top_n < len(sorted_sessions)
-    )
-    if top_n is not None:
-        sorted_sessions = sorted_sessions[:top_n]
-    # Basename-collision disambiguation: session-specific sibling of
-    # `_project_disambiguate_labels`. Without this, two `app/` sessions
-    # under different parents collapse to a single `project-N` after
-    # scrub — losing both privacy uniqueness and chart rank meaning.
-    augmented = _session_disambiguate_labels(sorted_sessions)
-    snap_rows: list = []
-    chart_pts: list = []
-    for idx, s in enumerate(sorted_sessions):
-        bare_label = (
-            os.path.basename(s.project_path or "")
-            or s.project_path
-            or "(unknown)"
-        )
-        proj_label = augmented.get(idx, bare_label)
-        cost_usd = float(getattr(s, "cost_usd", 0.0) or 0.0)
-        sid_short = (s.session_id[:8] if s.session_id else "—") or "—"
-        # Datetime chokepoint rule: route human-displayed timestamps
-        # through `format_display_dt` so `--tz` is honored (was
-        # `.astimezone()` which used host-local regardless of `--tz`).
-        # `suffix=False` keeps the cell width tight — the subtitle's
-        # period_label already carries the active tz.
-        last_str = format_display_dt(
-            s.last_activity, tz, fmt="%Y-%m-%d %H:%M", suffix=False,
-        )
-        models_text = ", ".join(s.models) if s.models else "—"
-        snap_rows.append(_lib_share.Row(cells={
-            "session": _lib_share.TextCell(sid_short),
-            "project": _lib_share.ProjectCell(proj_label),
-            "cost": _lib_share.MoneyCell(cost_usd),
-            "last_activity": _lib_share.TextCell(last_str),
-            "models": _lib_share.TextCell(models_text),
-        }))
-        chart_pts.append(_lib_share.ChartPoint(
-            x_label=proj_label,
-            x_value=cost_usd,
-            y_value=cost_usd,
-            project_label=proj_label,
-        ))
-    chart = (
-        _lib_share.HorizontalBarChart(
-            points=tuple(chart_pts), x_label="$", cap=15,
-        )
-        if chart_pts else None
-    )
-    notes: tuple[str, ...] = ()
-    if chart is not None and len(chart_pts) > 15:
-        notes = (
-            f"Showing top 15 in chart; table includes all {len(chart_pts)}.",
-        )
-    sum_cost = sum(p.y_value for p in chart_pts)
-    totals = (
-        _lib_share.Totalled(label="Sum", value=f"${sum_cost:,.2f}"),
-        _lib_share.Totalled(label="Sessions", value=str(len(chart_pts))),
-    )
-    if sorted_sessions:
-        if truncated:
-            title = f"Top {len(snap_rows)} sessions"
-        else:
-            title = (
-                f"Sessions — {period_start.strftime('%b %d')} → "
-                f"{period_end.strftime('%b %d')}"
-            )
-    else:
-        title = "Sessions — no data"
-    period_label = _share_period_label(period_start, period_end, display_tz)
-    subtitle = " · ".join([
-        period_label,
-        theme,
-        "real projects" if reveal_projects else "projects anonymized",
-    ])
-    return _lib_share.ShareSnapshot(
-        cmd="session",
-        title=title,
-        subtitle=subtitle,
-        period=_lib_share.PeriodSpec(
-            start=period_start, end=period_end,
-            display_tz=display_tz, label=period_label,
-        ),
-        columns=columns, rows=tuple(snap_rows),
-        chart=chart, totals=totals, notes=notes,
-        generated_at=_share_now_utc(), version=version,
-    )
-
-
-# ---- v2 share panel_data builders (spec §5.2, plan M1.6) -------------
-#
-# These translate the live dashboard `DataSnapshot` into the dict shapes
-# the M1.4 Recap builders (in `bin/_lib_share_templates.py`) consume.
-# They're a thin extract step — the DataSnapshot was already built by
-# the sync thread, so this path doesn't re-query the DB on the share
-# hot path.
-#
-# Per-panel shape contracts live in each Recap builder's docstring in
-# `bin/_lib_share_templates.py` (see `_build_<panel>_recap`); the keys
-# below MUST stay in lockstep with those docstrings — the
-# producer/consumer contract.
-#
-# When the snapshot has no data for a given panel (fresh install, no
-# sync yet), the builder returns a minimal empty-shaped dict that the
-# downstream Recap builder renders as a "no data" snapshot (kernel
-# handles empty `weeks=[]` / `days=[]` / etc.).
-
-
-def _share_iso(value) -> "str | None":
-    """Coerce a datetime / ISO-string into an ISO-8601 string with `Z` suffix.
-
-    DataSnapshot mixes attribute types (`week_start_at` is a
-    `dt.datetime`; `WeeklyPeriodRow.week_start_at` is already a string).
-    Recap builders' `_parse_iso_utc` accepts both shapes via fromisoformat
-    + `Z`-swap, but normalizing here keeps the wire format consistent.
-    """
-    if value is None:
-        return None
-    if isinstance(value, dt.datetime):
-        v = value if value.tzinfo else value.replace(tzinfo=dt.timezone.utc)
-        return v.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-    return str(value)
-
-
-# ---- Period override (spec §6.2 Q4 + Codex P2 on PR #35) ----
-#
-# The share modal's Period control offers three kinds — current, previous,
-# custom — but the original render path consumed the dashboard's cached
-# DataSnapshot directly, which only ever holds "current" data. Override
-# semantics by panel:
-#
-#   panel        current             previous              custom (start/end)
-#   --------     ------------------  --------------------  -------------------
-#   weekly       this subscription   one week earlier      week containing end
-#                week
-#   daily        last 7 display-tz   7 days earlier        7 days ending at end
-#                days ending today
-#   monthly      last 12 months      12 months earlier     12 months ending at end
-#                ending now
-#   trend        last 8 weeks        8 weeks earlier       8 weeks ending at end
-#                ending now
-#   blocks       recent 5h blocks    blocks ending one     blocks ending at end
-#                                     5h-window earlier
-#   forecast     future projection   (rejected: previous
-#                from now             forecast doesn't exist)
-#   current-week this subscription   (rejected: panel IS current)
-#                week
-#   sessions     recent sessions     (deferred: ambiguous semantics — could
-#                                     mean "older sessions" or "sessions in
-#                                     date range"; revisit when use case clear)
-#
-# Override mechanics: derive a `now_utc` from the period option and
-# re-build only the relevant DataSnapshot field by calling the same
-# `_dashboard_build_*` function the sync thread uses, just with a
-# shifted `now_utc`. `dataclasses.replace` returns a new DataSnapshot
-# with that field swapped; everything downstream (panel_data builder,
-# template builder, kernel render) consumes it unchanged.
-#
-# Validation failures land on the request as HTTP 400 with
-# `field: "options.period.<key>"` so the UI can highlight the offending
-# control.
-
-def _share_render_and_emit(snap, args) -> None:
-    """End-to-end: scrub -> render -> emit -> optional open.
-
-    Lazy-imports `_lib_share` so non-share invocations don't pay the import
-    cost. The kernel module stays I/O-pure; this wrapper does all the
-    side-effecting glue (destination resolution, file writes, clipboard,
-    post-write `--open` launch).
-
-    Caller contract: ``args.format`` MUST be set ("md", "html", or "svg").
-    The wrapper raises ValueError if called without it — surfaces the
-    contract failure at the chokepoint instead of producing junk filenames
-    like ``cctally-daily-<date>.None``.
-    """
-    if args.format is None:
-        raise ValueError("_share_render_and_emit called without args.format")
-    if args.open_after_write and args.format == "md":
-        # Spec Section 4.4: --open is only meaningful for html/svg writes.
-        # Reject explicitly with exit 2 instead of silently no-opping (which
-        # the prior implementation did because the open-after-write branch
-        # gates on ``kind == "file"``, and md routes to stdout by default).
-        print(
-            "cctally: --open is only valid with --format html or --format svg",
-            file=sys.stderr,
-        )
-        sys.exit(2)
-    # Routed through `_share_load_lib` so wrapper / builders / test harness
-    # share one cached module object — see helper docstring for the
-    # class-identity invariant this enforces.
-    _lib_share = _share_load_lib()
-
-    scrubbed = _lib_share._scrub(snap, reveal_projects=args.reveal_projects)
-    rendered = _lib_share.render(
-        scrubbed,
-        format=args.format,
-        theme=args.theme,
-        branding=not args.no_branding,
-    )
-
-    utc_date = snap.generated_at.astimezone(dt.timezone.utc).strftime("%Y-%m-%d")
-    kind, value = _resolve_destination(args, cmd=snap.cmd, generated_at_utc_date=utc_date)
-    _emit(rendered, kind=kind, value=value)
-
-    if args.open_after_write and kind == "file":
-        _share_open_file(pathlib.Path(value))
-
-
-def _share_open_file(path: pathlib.Path) -> None:
-    """Run `open` (macOS) / `xdg-open` (Linux). Silent fail if launcher missing."""
-    for launcher in ("open", "xdg-open"):
-        if shutil.which(launcher):
-            subprocess.Popen(
-                [launcher, str(path)],
-                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-            )
-            return
-    sys.stderr.write("cctally: --open requires `open` or `xdg-open` on PATH; skipped\n")
-
-
 # Phase F #23 (the FINAL Phase F extraction): ``bin/_cctally_tui.py`` is
 # loaded eagerly per spec §4.8 carve-out — ``tests/test_dashboard_*.py``
 # and ``tests/test_tui_*.py`` reach into TUI symbols via ``ns["X"]``