cctally 1.2.0 → 1.4.0

package/bin/cctally

@@ -83,7 +83,17 @@ SETUP_HOOK_EVENTS = ("PostToolBatch", "Stop", "SubagentStop")
 
 # === Release automation (issue #24) ===
 
-CHANGELOG_PATH = pathlib.Path(__file__).resolve().parent.parent / "CHANGELOG.md"
+_CHANGELOG_OVERRIDE = os.environ.get("CCTALLY_TEST_CHANGELOG_PATH")
+if _CHANGELOG_OVERRIDE:
+    # Fixture-stability hook for `bin/cctally-share-test` — points
+    # `_share_resolve_version()` (and the broader release machinery) at a
+    # per-scenario CHANGELOG so version stamping in goldens stays
+    # deterministic regardless of the in-tree CHANGELOG state. Mirrors the
+    # `CCTALLY_AS_OF` env-only precedent: not in --help, no docstring
+    # surface; consumed exclusively by harness wrappers.
+    CHANGELOG_PATH = pathlib.Path(_CHANGELOG_OVERRIDE)
+else:
+    CHANGELOG_PATH = pathlib.Path(__file__).resolve().parent.parent / "CHANGELOG.md"
 
 
 def _package_json_path() -> pathlib.Path:
@@ -1446,79 +1456,82 @@ def _release_run_phase_gh(version: str, body: str) -> int:
     return 0
 
 
+_RELEASE_NPM_POLL_TIMEOUT_S_DEFAULT = 300.0
+_RELEASE_NPM_POLL_INTERVAL_S_DEFAULT = 10.0
+
+
+def _release_npm_poll_timing() -> tuple[float, float]:
+    """Return (timeout_s, interval_s) honoring env-hook overrides.
+
+    Hidden env hooks (mirrors ``CCTALLY_RELEASE_DATE_UTC``):
+      - CCTALLY_RELEASE_NPM_POLL_TIMEOUT_S
+      - CCTALLY_RELEASE_NPM_POLL_INTERVAL_S
+    Used by the harness (and pytest) to make Phase 5 fixtures deterministic.
+    Not in --help.
+    """
+    def _f(name: str, default: float) -> float:
+        try:
+            return float(os.environ[name])
+        except (KeyError, ValueError):
+            return default
+    return (
+        _f("CCTALLY_RELEASE_NPM_POLL_TIMEOUT_S", _RELEASE_NPM_POLL_TIMEOUT_S_DEFAULT),
+        _f("CCTALLY_RELEASE_NPM_POLL_INTERVAL_S", _RELEASE_NPM_POLL_INTERVAL_S_DEFAULT),
+    )
+
+
 def _release_run_phase_npm(
     version: str,
     public_clone: pathlib.Path,
     *,
     dist_tag: str,
 ) -> int:
-    """Phase 5 — publish to npm from the public clone.
+    """Phase 5 — wait for the public-repo GHA workflow to publish ``cctally@<v>``.
 
-    ``dist_tag`` is ``"latest"`` for stable releases, ``"next"`` for
-    prereleases. Idempotent: short-circuits when
-    ``_release_phase_npm_done`` reports the version is already on npm.
+    Phase 3 pushes ``v<version>`` to ``omrikais/cctally``; the workflow at
+    ``.github/workflows/release-npm.yml`` fires on tag-push and runs
+    ``npm publish --provenance`` via OIDC trusted publisher (no NPM_TOKEN,
+    no operator 2FA round-trip — fixes the passkey-in-subprocess failure
+    mode where npm 2FA blocks ``npm publish`` from a non-interactive
+    subprocess).
 
-    Auth-fallback parity with Phase 4: when ``npm whoami`` exits
-    nonzero (or npm isn't on PATH at all), prints a copy-pasteable
-    command to publish manually and returns 0 — phases 1-4 already
-    succeeded, the release IS published to GitHub from the user's
-    perspective; npm is the third channel and treated as polish.
+    Phase 5 here is observation-only: poll ``npm view cctally@<v>`` until
+    it appears, with timeout. ``cctally`` never invokes ``npm publish``
+    locally anymore — Trusted Publisher binds the right to publish to the
+    public-repo workflow, not to the operator's `npm login` token.
 
-    Returns:
-      - ``0`` on successful publish, idempotent short-circuit, OR
-        auth-fallback.
-      - ``3`` on hard failure of ``npm publish`` after auth was
-        confirmed OK; ``--resume`` retries.
+    Returns ``0`` on observed success OR poll-timeout (soft-success: phases
+    1-4 landed; the workflow is either succeeding or visibly failing on
+    github.com; ``--resume`` re-checks the registry).
+
+    Timing overridable via ``CCTALLY_RELEASE_NPM_POLL_TIMEOUT_S`` and
+    ``CCTALLY_RELEASE_NPM_POLL_INTERVAL_S`` env vars.
     """
-    print(f"phase 5: npm publish (tag={dist_tag})")
+    print(f"phase 5: await npm publish via GHA (tag={dist_tag})")
     if _release_phase_npm_done(version):
         print(f"  cctally@{version} already on npm — skipping.")
         return 0
 
-    # Auth probe. Wrap in try/except so missing npm-on-PATH falls
-    # cleanly into the auth-fallback branch (existing release-test
-    # scenarios run without npm on PATH and depend on this not crashing).
-    try:
-        auth = subprocess.run(
-            ["npm", "whoami"],
-            capture_output=True,
-            text=True,
-            check=False,
-            timeout=15,
-        )
-    except (subprocess.TimeoutExpired, FileNotFoundError):
-        print(
-            f"\n  npm not on PATH or unresponsive. After installing npm and "
-            f"`npm login`, run:\n"
-            f"    cd {public_clone} && npm publish --tag {dist_tag}\n",
-            file=sys.stderr,
-        )
-        return 0
-    if auth.returncode != 0:
-        print(
-            f"\n  npm not authenticated. After `npm login`, run:\n"
-            f"    cd {public_clone} && npm publish --tag {dist_tag}\n",
-            file=sys.stderr,
-        )
-        return 0
-
-    pub = subprocess.run(
-        ["npm", "publish", "--tag", dist_tag],
-        cwd=str(public_clone),
-        check=False,
-    )
-    if pub.returncode != 0:
-        return 3
-
-    if not _release_phase_npm_done(version):
-        print(
-            f"  warning: `npm publish` returned 0 but `npm view "
-            f"cctally@{version}` doesn't see the version yet. Registry "
-            f"propagation lag is normal; check `npm view cctally version` "
-            f"in 30s.",
-            file=sys.stderr,
-        )
-    return 0
+    timeout_s, interval_s = _release_npm_poll_timing()
+    deadline = time.monotonic() + timeout_s
+    while True:
+        if _release_phase_npm_done(version):
+            print(f"  cctally@{version} on npm registry ✓")
+            return 0
+        if time.monotonic() >= deadline:
+            print(
+                f"\n  timed out after {timeout_s:.0f}s waiting for "
+                f"cctally@{version} on npm. The GHA workflow may still be "
+                f"running or have failed — check:\n"
+                f"    https://github.com/{PUBLIC_REPO}/actions\n"
+                f"  Re-run `cctally release --resume` once the workflow "
+                f"completes, or for emergency manual publish:\n"
+                f"    cd {public_clone} && npm publish --access public "
+                f"--tag {dist_tag}\n",
+                file=sys.stderr,
+            )
+            return 0
+        time.sleep(interval_s)
 
 
 def _release_run_phase_brew(
@@ -1538,8 +1551,8 @@ def _release_run_phase_brew(
         version (idempotency under ``--resume``).
       - Dirty working tree — refuses with exit 2 and points the operator
         at ``--resume``.
-      - Push failure — auth-fallback parity with Phases 4 and 5: prints
-        the exact recovery command and returns 0. Phases 1-5 already
+      - Push failure — auth-fallback parity with Phase 4: prints the
+        exact recovery command and returns 0. Phases 1-5 already
         succeeded, the release IS published from the user's
         perspective; the brew tap is the third channel and treated as
         polish.
@@ -1620,8 +1633,40 @@ def _release_run_phase_brew(
         )
     # Tag is best-effort — re-running after a partial publish should
     # not fail just because the tag already exists locally.
+    #
+    # Annotated form with `-m` (issue #25): plain `git tag <name>` is
+    # silently upgraded to `git tag -s <name>` under operator-global
+    # `tag.gpgsign=true` and demands a message via editor. The release
+    # script has no editor stdin, so git aborts with `fatal: no tag
+    # message?` — the atomic push refspec then fails with "src refspec
+    # does not match any" because the local tag was never created, and
+    # the auth-fallback branch below silently swallows the failure as
+    # exit 0. Mirrors Phase 2's signing detection (signing_key +
+    # tag.gpgsign → -s, else fall back), with one defensive divergence:
+    # the fallback uses --no-sign (not bare -a) so the tag still lands
+    # under tag.gpgsign=true without a usable signing key configured.
+    # Brew install reads the formula off the tap's default branch, not
+    # the tag, so signing the tap tag is operationally moot — it exists
+    # for history bookkeeping and atomic-push transport.
+    signing_key = subprocess.run(
+        ["git", "-C", str(brew_clone), "config", "--get", "user.signingkey"],
+        capture_output=True,
+        text=True,
+    ).stdout.strip()
+    tag_gpgsign = (
+        subprocess.run(
+            ["git", "-C", str(brew_clone), "config", "--get", "tag.gpgsign"],
+            capture_output=True,
+            text=True,
+        )
+        .stdout.strip()
+        .lower()
+        == "true"
+    )
+    sign_flag = "-s" if (signing_key and tag_gpgsign) else "--no-sign"
     subprocess.run(
-        ["git", "-C", str(brew_clone), "tag", f"v{version}"],
+        ["git", "-C", str(brew_clone), "tag", sign_flag, "-a", "-m",
+         f"cctally v{version}", f"v{version}"],
         check=False,
     )
     # Single ATOMIC push of branch + tag in one transaction — the
@@ -1630,22 +1675,29 @@ def _release_run_phase_brew(
     # split branch-push + tag-push pair admits: a tag landing without
     # the branch landing would leave `brew install` serving the OLD
     # formula off the tap's default branch even though the remote
-    # carries the new tag. Tag refspec is explicit (`src:dst`) because
-    # `--follow-tags` skips lightweight tags and Phase 6's tag is
-    # lightweight (no `-a`/`-m`).
+    # carries the new tag. Tag refspec is explicit (`src:dst`) for
+    # atomic-push semantics — `--atomic` requires named refs, not the
+    # implicit `--follow-tags` path.
     push = subprocess.run(
         ["git", "-C", str(brew_clone), "push", "--atomic", "origin",
          "HEAD", f"refs/tags/v{version}:refs/tags/v{version}"],
         check=False,
     )
     if push.returncode != 0:
+        # If the local tag isn't there (e.g., the operator hit the
+        # tag.gpgsign edge case from issue #25 even with the fix), the
+        # plain push refspec fails. Surface a tag-create fallback in
+        # the hint so copy-paste recovery is self-contained.
         print(
             f"\n  push failed. Manual recovery:\n"
+            f"    # If local tag v{version} is missing (e.g., gpgsign issue):\n"
+            f"    git -C {brew_clone} tag --no-sign -a -m \"cctally v{version}\" v{version}\n"
+            f"    # Then push:\n"
             f"    git -C {brew_clone} push --atomic origin HEAD "
             f"refs/tags/v{version}:refs/tags/v{version}\n",
             file=sys.stderr,
         )
-        return 0  # auth-fallback semantics; mirrors Phase 5.
+        return 0  # auth-fallback semantics; parity with Phase 4.
 
     return 0
 
@@ -1846,10 +1898,12 @@ def cmd_release(args: argparse.Namespace) -> int:
     is_prerelease = "-" in next_v
     dist_tag = "next" if is_prerelease else "latest"
 
-    # Phase 5 — npm publish (auth-fallback returns 0 to keep the release
-    # "published" from phases 1-4's perspective). `--skip-npm` is the
-    # operator escape hatch for ad-hoc cuts; idempotent — re-running
-    # `--resume` without it picks Phase 5 back up.
+    # Phase 5 — await npm publish via the public-repo GHA workflow
+    # (release-npm.yml), which fires on the tag pushed in Phase 3. Phase 5
+    # here is observation-only (poll `npm view` with timeout); poll-timeout
+    # returns 0 — the workflow runs independently on github.com, and
+    # `--resume` re-checks the registry. `--skip-npm` is the operator
+    # escape hatch for ad-hoc cuts.
     if args.skip_npm:
         print("phase 5: npm skipped (--skip-npm)")
     else:
@@ -1973,8 +2027,8 @@ def _release_dry_run(
     else:
         dist_tag = "next" if "-" in next_v else "latest"
         print(
-            f"Would publish: cctally@{next_v} to npmjs.org "
-            f"with --tag {dist_tag}"
+            f"Would await: cctally@{next_v} on npmjs.org via GHA workflow "
+            f"(release-npm.yml in public repo; tag={dist_tag})"
         )
     print()
     # Phase 6 — brew formula bump plan.
@@ -8185,6 +8239,41 @@ def _render_claude_session_table(
     return "\n".join(out)
 
 
+def _project_disambiguate_labels(rows: list[dict]) -> dict[int, str]:
+    """Return ``{row_index: disambiguated_label}`` for project rows whose
+    bare ``display_key`` collides with another row's basename.
+
+    When two projects share a basename (e.g., two ``app`` directories under
+    different parents), suffix the colliding rows with the parent-directory
+    segment ("(work)" / "(personal)") so they remain visually and
+    semantically distinct. Prefer ``key.git_root`` as the disambiguation
+    source when present; fall back to ``key.bucket_path`` for no-git rows.
+
+    Used by:
+      - ``_render_project_table`` (terminal table render).
+      - ``_build_project_snapshot`` (share artifact table + chart) — without
+        this, two same-basename projects collapse to a single anonymous
+        ``project-N`` after scrub, losing rank meaning AND uniqueness.
+
+    Rows that do not collide are absent from the returned dict; callers
+    fall back to ``key.display_key`` for those.
+    """
+    display_counts: dict[str, int] = {}
+    for r in rows:
+        dk = r["key"].display_key
+        display_counts[dk] = display_counts.get(dk, 0) + 1
+    augmented: dict[int, str] = {}
+    for idx, r in enumerate(rows):
+        if display_counts[r["key"].display_key] > 1:
+            source_path = r["key"].git_root or r["key"].bucket_path
+            if source_path:
+                parent = (
+                    os.path.basename(os.path.dirname(source_path)) or "/"
+                )
+                augmented[idx] = f"{r['key'].display_key} ({parent})"
+    return augmented
+
+
 def _render_project_table(
     rows: list[dict],
     *,
@@ -8243,22 +8332,11 @@ def _render_project_table(
         ampm = "a.m." if local.hour < 12 else "p.m."
         return f"{local.year}-{local.month:02d}-{local.day:02d}\n{hour_12}:{local.minute:02d}\n{ampm}"
 
-    # Basename-collision disambiguation: if two rows share a display_key,
-    # suffix with the parent directory segment so the user can tell them
-    # apart. Prefer the git_root as the disambiguation source when present;
-    # fall back to bucket_path for no-git rows (whose displays also collide
-    # on basename even though they each carry a `(no-git)` marker).
-    display_counts: dict[str, int] = {}
-    for r in rows:
-        dk = r["key"].display_key
-        display_counts[dk] = display_counts.get(dk, 0) + 1
-    augmented: dict[int, str] = {}
-    for idx, r in enumerate(rows):
-        if display_counts[r["key"].display_key] > 1:
-            source_path = r["key"].git_root or r["key"].bucket_path
-            if source_path:
-                parent = os.path.basename(os.path.dirname(source_path)) or "/"
-                augmented[idx] = f"{r['key'].display_key} ({parent})"
+    # Basename-collision disambiguation: hoisted to a module-level helper
+    # so the share-snapshot builder can reuse the same logic (without it,
+    # two same-basename projects collapse to a single anonymous `project-N`
+    # after scrub, breaking both privacy uniqueness AND chart rank meaning).
+    augmented = _project_disambiguate_labels(rows)
 
     def _project_cell(idx: int, r: dict) -> tuple[str, Any]:
         """Return (plain_text, color_fn_or_None) for the Project cell.
@@ -12278,12 +12356,36 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                             )
                             pending_alerts.append(payload)
 
-            # ── Mid-week reset cross-flag (opportunistic, JOIN-based) ──
-            # Self-healing sweep against week_reset_events: every tick,
-            # flag any open block whose [block_start_at,
-            # last_observed_at_utc] interval contains a recorded reset
-            # moment. Symmetric with the historical-backfill predicate
-            # (§4.2 step 5). Idempotent (only flips 0 → 1).
+            # ── Reset-crossing cross-flag (opportunistic, JOIN-based) ──
+            # Self-healing sweep: every tick, flag any open block whose
+            # [block_start_at, last_observed_at_utc] interval crosses a
+            # weekly reset, from either of two sources:
+            #   (a) week_reset_events — Anthropic-shifted MID-week resets
+            #       (prior week_end_at was still in the future at detect
+            #       time; see cmd_record_usage's reset-event detection).
+            #   (b) weekly_usage_snapshots.week_start_at — NATURAL weekly
+            #       boundaries. These never get a week_reset_events row
+            #       (mid-week detection requires the prior end to be in
+            #       the future), so source (a) silently misses blocks
+            #       that span a routine week reset. Without this clause
+            #       the dashboard's "Δ pp this block" delta is computed
+            #       against the pre-reset 7d% (~94%) versus post-reset
+            #       (~0%) and renders as a misleading −94pp drop.
+            # Predicate (b) uses strict ``>`` on the lower bound so a
+            # block that starts EXACTLY at the boundary (post-reset) is
+            # not flagged.  Symmetric with the historical-backfill
+            # predicate (§4.2 step 5). Idempotent (only flips 0 → 1).
+            #
+            # Comparisons go through ``unixepoch()`` rather than a raw
+            # lex BETWEEN: ``parse_iso_datetime`` returns host-local
+            # tz-aware datetimes (line 9433: ``return parsed.astimezone()``),
+            # so ``block_start_at`` is stored with the host's display
+            # offset (e.g. ``+03:00``) while ``week_start_at`` is
+            # ``+00:00`` and ``last_observed_at_utc`` is ``Z``. A lex
+            # compare across mixed offsets silently mis-orders moments
+            # for non-UTC hosts; ``unixepoch()`` normalizes all three
+            # to seconds-since-epoch and is correct regardless of
+            # offset suffix.
             #
             # Why the JOIN rather than a per-tick param: an earlier
             # design passed mid_week_reset_at only on the tick that
@@ -12298,13 +12400,21 @@ def maybe_update_five_hour_block(saved: dict[str, Any]) -> None:
                 UPDATE five_hour_blocks
                    SET crossed_seven_day_reset = 1
                  WHERE crossed_seven_day_reset = 0
-                   AND id IN (
-                     SELECT b.id
-                       FROM five_hour_blocks b
-                       JOIN week_reset_events e
-                         ON e.effective_reset_at_utc
-                            BETWEEN b.block_start_at
-                                AND b.last_observed_at_utc
+                   AND (
+                     EXISTS (
+                       SELECT 1 FROM week_reset_events e
+                        WHERE unixepoch(e.effective_reset_at_utc)
+                              BETWEEN unixepoch(five_hour_blocks.block_start_at)
+                                  AND unixepoch(five_hour_blocks.last_observed_at_utc)
+                     )
+                     OR EXISTS (
+                       SELECT 1 FROM weekly_usage_snapshots ws
+                        WHERE ws.week_start_at IS NOT NULL
+                          AND unixepoch(ws.week_start_at)
+                              >  unixepoch(five_hour_blocks.block_start_at)
+                          AND unixepoch(ws.week_start_at)
+                              <= unixepoch(five_hour_blocks.last_observed_at_utc)
+                     )
                    )
                 """,
             )
@@ -12414,16 +12524,36 @@ def _backfill_five_hour_blocks(conn: sqlite3.Connection) -> int:
                 last_obs_dt = parse_iso_datetime(last_obs, "last_obs backfill")
 
                 # Cross-reset detection (interval predicate, symmetric with
-                # the live path's UPDATE in T4).
+                # the live path's UPDATE in T4). Two sources:
+                #   (a) week_reset_events — Anthropic-shifted mid-week resets.
+                #   (b) weekly_usage_snapshots.week_start_at — natural week
+                #       boundaries (no event row for these).
+                # Strict ``>`` on the lower bound for (b) so a block whose
+                # block_start_at coincides with a week boundary is not flagged.
+                # ``unixepoch()`` normalizes the comparison across mixed tz
+                # suffixes (block_start_at is host-local; week_start_at /
+                # effective_reset_at_utc are ``+00:00``); see the live-path
+                # comment for rationale.
                 cross_row = conn.execute(
                     """
                     SELECT 1 FROM week_reset_events
-                     WHERE effective_reset_at_utc >= ?
-                       AND effective_reset_at_utc <= ?
+                     WHERE unixepoch(effective_reset_at_utc) >= unixepoch(?)
+                       AND unixepoch(effective_reset_at_utc) <= unixepoch(?)
                      LIMIT 1
                     """,
                     (block_start_at, last_obs),
                 ).fetchone()
+                if cross_row is None:
+                    cross_row = conn.execute(
+                        """
+                        SELECT 1 FROM weekly_usage_snapshots
+                         WHERE week_start_at IS NOT NULL
+                           AND unixepoch(week_start_at) >  unixepoch(?)
+                           AND unixepoch(week_start_at) <= unixepoch(?)
+                         LIMIT 1
+                        """,
+                        (block_start_at, last_obs),
+                    ).fetchone()
                 crossed = 1 if cross_row is not None else 0
 
                 # is_closed: 1 if the canonical reset moment is already past.
@@ -14203,6 +14333,7 @@ def cmd_cache_sync(args: argparse.Namespace) -> int:
 
 def cmd_daily(args: argparse.Namespace) -> int:
     """Show usage report grouped by display-timezone date."""
+    _share_validate_args(args)
     config = load_config()
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
@@ -14220,6 +14351,35 @@ def cmd_daily(args: argparse.Namespace) -> int:
     # Aggregate by display-tz date (Q5/F6: day boundary follows display.tz).
     days = _aggregate_daily(all_entries, mode="auto", tz=tz)
 
+    # Shareable-reports gate: --format short-circuits the JSON / table
+    # dispatch via `_share_render_and_emit`. The mutex in
+    # `_add_share_args` keeps `--format` and `--json` from coexisting.
+    # Gate runs BEFORE the `--order desc` reversal so the BarChart bars
+    # render chronologically regardless of `--order`. Table rows in the
+    # rendered artifact, however, must respect `--order desc` (parity
+    # with terminal / JSON output) — handled by reversing snap.rows
+    # post-build below; the chart points stay chronological because
+    # they were built from ascending `days`.
+    if getattr(args, "format", None):
+        # Note: --breakdown is a no-op under --format (snapshot focuses on
+        # the headline daily-cost trend; per-model sub-rows aren't in the
+        # share spec scope). Same convention applies to other share-enabled
+        # subcommands (cmd_report's --detail, etc.).
+        display_tz_str = _share_display_tz_label(tz)
+        snap = _build_daily_snapshot(
+            days,
+            period_start=range_start,
+            period_end=range_end,
+            display_tz=display_tz_str,
+            version=_share_resolve_version(),
+            theme=args.theme,
+            reveal_projects=args.reveal_projects,
+        )
+        if args.order == "desc":
+            snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
+        _share_render_and_emit(snap, args)
+        return 0
+
     # Apply sort order.
     if args.order == "desc":
         days = list(reversed(days))
@@ -14241,6 +14401,7 @@ def cmd_daily(args: argparse.Namespace) -> int:
 
 def cmd_monthly(args: argparse.Namespace) -> int:
     """Show usage report grouped by display-timezone calendar month."""
+    _share_validate_args(args)
     config = load_config()
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
@@ -14256,6 +14417,32 @@ def cmd_monthly(args: argparse.Namespace) -> int:
 
     months = _aggregate_monthly(all_entries, mode="auto", tz=tz)
 
+    # Shareable-reports gate: --format short-circuits the JSON / table
+    # dispatch via `_share_render_and_emit`. The mutex in
+    # `_add_share_args` keeps `--format` and `--json` from coexisting.
+    # Gate runs BEFORE the `--order desc` reversal so the BarChart bars
+    # render chronologically regardless of `--order`. Table rows in the
+    # rendered artifact respect `--order desc` (parity with terminal /
+    # JSON) via post-build snap.rows reversal; chart stays chronological.
+    if getattr(args, "format", None):
+        # Note: --breakdown is a no-op under --format (snapshot focuses on
+        # the headline monthly-cost trend; per-model sub-rows aren't in the
+        # share spec scope). Same convention as cmd_daily / cmd_report.
+        display_tz_str = _share_display_tz_label(tz)
+        snap = _build_monthly_snapshot(
+            months,
+            period_start=range_start,
+            period_end=range_end,
+            display_tz=display_tz_str,
+            version=_share_resolve_version(),
+            theme=args.theme,
+            reveal_projects=args.reveal_projects,
+        )
+        if args.order == "desc":
+            snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
+        _share_render_and_emit(snap, args)
+        return 0
+
     if args.order == "desc":
         months = list(reversed(months))
 
@@ -14275,6 +14462,7 @@ def cmd_monthly(args: argparse.Namespace) -> int:
 
 def cmd_weekly(args: argparse.Namespace) -> int:
     """Show Claude usage grouped by subscription week."""
+    _share_validate_args(args)
     config = load_config()
     args._resolved_tz = resolve_display_tz(args, config)
 
@@ -14351,6 +14539,33 @@ def cmd_weekly(args: argparse.Namespace) -> int:
         else:
             overlay.append((None, None))
 
+    # Shareable-reports gate: --format short-circuits the JSON / table
+    # dispatch via `_share_render_and_emit`. The mutex in
+    # `_add_share_args` keeps `--format` and `--json` from coexisting.
+    # Gate runs BEFORE the `--order desc` reversal so the BarChart bars
+    # render chronologically regardless of `--order`. Table rows in the
+    # rendered artifact respect `--order desc` (parity with terminal /
+    # JSON) via post-build snap.rows reversal. `--breakdown` is honored:
+    # when set, the snapshot adds per-model columns + stacked bar series
+    # (vs. cmd_daily / cmd_monthly where --breakdown is a no-op under
+    # --format).
+    if getattr(args, "format", None):
+        display_tz_str = _share_display_tz_label(args._resolved_tz)
+        snap = _build_weekly_snapshot(
+            buckets, overlay,
+            period_start=range_start,
+            period_end=range_end,
+            display_tz=display_tz_str,
+            version=_share_resolve_version(),
+            theme=args.theme,
+            reveal_projects=args.reveal_projects,
+            breakdown_model=bool(getattr(args, "breakdown", False)),
+        )
+        if args.order == "desc":
+            snap = dataclasses.replace(snap, rows=tuple(reversed(snap.rows)))
+        _share_render_and_emit(snap, args)
+        return 0
+
     # Apply sort order. Buckets and overlay must reverse together so their
     # indices stay aligned (both _render_weekly_table and _weekly_to_json
     # assert len equality).
@@ -14819,6 +15034,7 @@ def _project_sort_key(row: dict, sort_by: str, order: str):
 
 def cmd_project(args: argparse.Namespace) -> int:
     """Roll entries up by project (git-root) with per-project usage attribution."""
+    _share_validate_args(args)
     config = load_config()
     args._resolved_tz = resolve_display_tz(args, config)
 
@@ -15157,6 +15373,33 @@ def cmd_project(args: argparse.Namespace) -> int:
             key=lambda r: _project_sort_key(r, args.sort, args.order),
         )
 
+    # Shareable-reports gate: --format short-circuits the JSON / table
+    # dispatch via `_share_render_and_emit`. The mutex in
+    # `_add_share_args` keeps `--format` and `--json` from coexisting.
+    # Privacy invariant (Section 8.4 / 5.3): the wrapper runs `_lib_share._scrub`
+    # before rendering, so default output anonymizes project labels to
+    # `project-1` / `project-2` / ...; `--reveal-projects` opts back in.
+    # The builder populates `ProjectCell.label` / `ChartPoint.project_label`
+    # / `ChartPoint.x_label` with REAL names; the wrapper-level scrubber is
+    # the single chokepoint that rewrites them.
+    if getattr(args, "format", None):
+        # Note: --breakdown is a no-op under --format (snapshot focuses on
+        # the headline per-project usage table + HBar chart; per-model
+        # sub-rows aren't in the share spec scope). Same convention as
+        # cmd_daily / cmd_weekly / cmd_report.
+        display_tz_str = _share_display_tz_label(args._resolved_tz)
+        snap = _build_project_snapshot(
+            list(sorted_rows),
+            period_start=since_dt,
+            period_end=until_dt,
+            display_tz=display_tz_str,
+            version=_share_resolve_version(),
+            theme=args.theme,
+            reveal_projects=args.reveal_projects,
+        )
+        _share_render_and_emit(snap, args)
+        return 0
+
     if args.json:
         print(_project_json_output(
             since=since_dt,
@@ -16762,6 +17005,7 @@ def cmd_diff(args: argparse.Namespace) -> int:
 
 def cmd_session(args: argparse.Namespace) -> int:
     """Show Claude usage grouped by sessionId (merges resumed-across-files sessions)."""
+    _share_validate_args(args)
     config = load_config()
     tz = resolve_display_tz(args, config)
     args._resolved_tz = tz
@@ -16775,6 +17019,52 @@ def cmd_session(args: argparse.Namespace) -> int:
 
     entries = get_claude_session_entries(range_start, range_end)
     sessions = _aggregate_claude_sessions(entries)
+
+    # Shareable-reports gate: --format short-circuits the JSON / table
+    # dispatch via `_share_render_and_emit`. The mutex in
+    # `_add_share_args` keeps `--format` and `--json` from coexisting.
+    # Privacy invariant (Section 8.4 / 5.3): the wrapper runs `_lib_share._scrub`
+    # before rendering, so default output anonymizes project labels to
+    # `project-1` / `project-2` / ...; `--reveal-projects` opts back in.
+    # The builder populates `ProjectCell.label` / `ChartPoint.project_label`
+    # / `ChartPoint.x_label` with REAL basenames; the wrapper-level scrubber
+    # is the single chokepoint that rewrites them.
+    if getattr(args, "format", None):
+        # --top-n validation. Spec convention (Implementor 6 fix-loop):
+        # invalid flag combinations exit 2; the soft-warn upper threshold
+        # (>50) writes to stderr but proceeds.
+        top_n = getattr(args, "top_n", None)
+        if top_n is not None:
+            if top_n < 1:
+                print(
+                    "cctally: --top-n must be >= 1",
+                    file=sys.stderr,
+                )
+                return 2
+            if top_n > 50:
+                sys.stderr.write(
+                    f"cctally: --top-n {top_n} will likely produce an "
+                    "unreadable chart (consider 15 or fewer)\n"
+                )
+        # Note: --breakdown is a no-op under --format (snapshot focuses
+        # on the headline per-session usage table + HBar chart; per-model
+        # sub-rows aren't in the share spec scope). Same convention as
+        # cmd_daily / cmd_project.
+        display_tz_str = _share_display_tz_label(tz)
+        snap = _build_session_snapshot(
+            sessions,
+            period_start=range_start,
+            period_end=range_end,
+            display_tz=display_tz_str,
+            version=_share_resolve_version(),
+            theme=args.theme,
+            reveal_projects=args.reveal_projects,
+            top_n=top_n,
+            tz=tz,
+        )
+        _share_render_and_emit(snap, args)
+        return 0
+
     # Aggregator returns descending by last_activity; --order asc reverses.
     if args.order == "asc":
         sessions = list(reversed(sessions))
@@ -18019,6 +18309,7 @@ def _render_forecast_terminal(out: "ForecastOutput", args, color: bool) -> str:
 
 
 def cmd_report(args: argparse.Namespace) -> int:
+    _share_validate_args(args)
     if args.sync_current:
         sync_ns = argparse.Namespace(
             week_start=None,
@@ -18066,6 +18357,40 @@ def cmd_report(args: argparse.Namespace) -> int:
 
         weeks = get_recent_weeks(conn, max(1, args.weeks))
         if not weeks:
+            # Format-aware empty path mirrors cmd_forecast:18578-18629 — a
+            # fresh install requesting `report --format html` should emit a
+            # uniformly-shaped artifact, not a free-form "No data yet"
+            # sentence the share consumer can't parse.
+            if getattr(args, "format", None):
+                display_tz_str = _share_display_tz_label(tz)
+                # Anchor the period_label on the current subscription
+                # week so the artifact's subtitle is meaningful (the
+                # week the report WOULD describe if data existed).
+                # `_command_as_of()` honors CCTALLY_AS_OF — keeps the
+                # period_label coherent with `generated_at` (which goes
+                # through `_share_now_utc` from the same env hook) so
+                # fixture goldens don't drift when the harness host's
+                # wall-clock day rolls past CCTALLY_AS_OF.
+                now_local = _command_as_of().astimezone(tz)
+                local_tz = now_local.tzinfo
+                ws_d, we_d = compute_week_bounds(now_local, week_start_name)
+                ws_dt = dt.datetime.combine(
+                    ws_d, dt.time.min, tzinfo=local_tz
+                )
+                we_dt = dt.datetime.combine(
+                    we_d + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
+                )
+                snap = _build_report_snapshot(
+                    [],
+                    period_start=ws_dt,
+                    period_end=we_dt,
+                    display_tz=display_tz_str,
+                    version=_share_resolve_version(),
+                    theme=args.theme,
+                    reveal_projects=args.reveal_projects,
+                )
+                _share_render_and_emit(snap, args)
+                return 0
             if args.json:
                 print(json.dumps({"current": None, "trend": []}, indent=2))
             else:
@@ -18178,6 +18503,39 @@ def cmd_report(args: argparse.Namespace) -> int:
                 for m in milestone_rows
             ]
 
+        # Shareable-reports gate: --format short-circuits the terminal/JSON
+        # paths. The mutex in `_add_share_args` guarantees --format and
+        # --json are not both set, so checking --format first is unambiguous.
+        # Snapshot rows are reversed to ascending chronological order so
+        # the line chart trends left->right with time (`get_recent_weeks`
+        # returns newest-first; `trend` mirrors that order).
+        if getattr(args, "format", None):
+            # Note: --detail is a no-op under --format (snapshot focuses on
+            # the headline weekly-trend table + chart; per-percent milestone
+            # detail isn't in the share spec scope). Same convention applies
+            # to other share-enabled subcommands (cmd_daily's --breakdown,
+            # etc.).
+            ordered_trend = list(reversed(trend))
+            if ordered_trend:
+                first_wsd = ordered_trend[0].get("weekStartDate")
+                last_wed = ordered_trend[-1].get("weekEndDate") or ordered_trend[-1].get("weekStartDate")
+                period_start = _share_parse_date_to_dt(first_wsd, tz)
+                period_end = _share_parse_date_to_dt(last_wed, tz)
+            else:
+                period_start = period_end = _share_now_utc()
+            display_tz_str = _share_display_tz_label(tz)
+            snap = _build_report_snapshot(
+                ordered_trend,
+                period_start=period_start,
+                period_end=period_end,
+                display_tz=display_tz_str,
+                version=_share_resolve_version(),
+                theme=args.theme,
+                reveal_projects=args.reveal_projects,
+            )
+            _share_render_and_emit(snap, args)
+            return 0
+
         if args.json:
             print(json.dumps(output, indent=2))
             return 0
@@ -18289,6 +18647,7 @@ def cmd_forecast(args: argparse.Namespace) -> int:
     """Project current-week usage to reset boundary. Emit terminal report,
     JSON, or status-line one-liner. See docs/commands/forecast.md.
     """
+    _share_validate_args(args)
     if args.json and args.status_line:
         print("forecast: --json and --status-line are mutually exclusive",
               file=sys.stderr)
@@ -18314,6 +18673,58 @@ def cmd_forecast(args: argparse.Namespace) -> int:
     inputs = _load_forecast_inputs(conn, now_utc, skip_sync=args.no_sync)
     if inputs is None:
         # No snapshot for the current week.
+        if getattr(args, "format", None):
+            # Shareable-reports empty-data path: emit a "no data" snapshot
+            # rather than a free-form text message so consumers of the share
+            # output (md / html / svg) get a uniformly-shaped artifact.
+            #
+            # Compute the real subscription-week boundaries from config
+            # rather than collapsing to a 0-duration `now → now` window —
+            # the period_label in the artifact's subtitle is meaningful
+            # (the week the forecast WOULD describe if data existed).
+            # Lift the `dt.date` boundaries from `compute_week_bounds`
+            # to tz-aware datetimes anchored on local midnight so the
+            # PeriodSpec stays consistent with sibling builders.
+            tz = getattr(args, "_resolved_tz", None)
+            display_tz_str = _share_display_tz_label(tz)
+            week_start_name = get_week_start_name(
+                config, getattr(args, "week_start_name", None)
+            )
+            ws_date, we_date = compute_week_bounds(now_utc, week_start_name)
+            # internal fallback: host-local intentional
+            local_tz = dt.datetime.now().astimezone().tzinfo
+            week_start_dt = dt.datetime.combine(
+                ws_date, dt.time.min, tzinfo=local_tz
+            )
+            week_end_dt = dt.datetime.combine(
+                we_date + dt.timedelta(days=1), dt.time.min, tzinfo=local_tz
+            )
+            # Pass `low_conf=False` + explicit notes: the issue is "no data
+            # recorded yet," not "thin data." LOW CONF would mislead the
+            # reader into thinking a projection ran with sparse samples.
+            snap = _build_forecast_snapshot(
+                week_start=week_start_dt,
+                week_end=week_end_dt,
+                display_tz=display_tz_str,
+                version=_share_resolve_version(),
+                theme=args.theme,
+                reveal_projects=args.reveal_projects,
+                actual_series=[],
+                projected_series=[],
+                current_pct=0.0,
+                projected_low_pct=0.0,
+                projected_high_pct=0.0,
+                days_remaining=0.0,
+                dollars_per_percent=0.0,
+                dollars_per_percent_source="this_week",
+                low_conf=False,
+                notes=(
+                    "No snapshots recorded for this week yet — run "
+                    "cctally record-usage to populate.",
+                ),
+            )
+            _share_render_and_emit(snap, args)
+            return 0
         if args.json:
             print(json.dumps({
                 "error": "no_current_week_data",
@@ -18327,6 +18738,94 @@ def cmd_forecast(args: argparse.Namespace) -> int:
 
     output = _compute_forecast(inputs, targets)
 
+    # Shareable-reports gate: --format short-circuits the JSON / status-line /
+    # terminal dispatch via `_share_render_and_emit`. The mutex in
+    # `_add_share_args(has_status_line=True)` keeps `--format`, `--json`, and
+    # `--status-line` from coexisting. The gate fires AFTER `_compute_forecast`
+    # so the snapshot reuses the same projection math as the terminal/JSON
+    # paths — no parallel computation.
+    if getattr(args, "format", None):
+        i = output.inputs
+        # Re-fetch the samples for the LineChart's actual_series. The
+        # `_load_forecast_inputs` path dropped them after deriving p_now /
+        # p_24h_ago / snapshot_count; re-running `_fetch_current_week_snapshots`
+        # is a single indexed query against `weekly_usage_snapshots` and only
+        # fires when `--format` is requested, so the cost is bounded.
+        # `_apply_midweek_reset_override` is replayed so the chart axis
+        # matches the (possibly-shifted) week_start_at carried by `inputs`.
+        fetched = _fetch_current_week_snapshots(conn, now_utc)
+        actual_series: list[tuple[str, float, float]] = []
+        if fetched is not None:
+            _ws_at, _we_at, raw_samples = fetched
+            _ws_at_shifted, samples = _apply_midweek_reset_override(
+                conn, _ws_at, _we_at, raw_samples
+            )
+            tz_render = getattr(args, "_resolved_tz", None)
+            for cap_at, pct, _five_hr in samples:
+                elapsed_h = (
+                    (cap_at - i.week_start_at).total_seconds() / 3600.0
+                )
+                lbl = format_display_dt(
+                    cap_at, tz_render, fmt="%a %H:%M", suffix=False,
+                )
+                actual_series.append((lbl, elapsed_h, float(pct)))
+        # Projected series: a 2-point ray from (now, p_now) to
+        # (week_end, projected_high). The high-end matches the terminal
+        # render's "may cap" warning so the chart and table tell the same
+        # story. When `already_capped` is true the ray collapses to a flat
+        # horizontal line at p_now from (now → week_end) — visually
+        # signals "you are pinned at the cap; no further growth expected"
+        # instead of the visually-empty (no-projection) chart that was
+        # confusable with "no projection computed."
+        projected_series: list[tuple[str, float, float]] = []
+        if i.remaining_hours > 0:
+            tz_render = getattr(args, "_resolved_tz", None)
+            now_label = format_display_dt(
+                i.now_utc, tz_render, fmt="%a %H:%M", suffix=False,
+            )
+            end_label = format_display_dt(
+                i.week_end_at, tz_render, fmt="%a %H:%M", suffix=False,
+            )
+            now_x = (i.now_utc - i.week_start_at).total_seconds() / 3600.0
+            end_x = (i.week_end_at - i.week_start_at).total_seconds() / 3600.0
+            if output.already_capped:
+                # Flat ray: y stays at p_now across the remaining window.
+                projected_series.append(
+                    (now_label, now_x, float(i.p_now))
+                )
+                projected_series.append(
+                    (end_label, end_x, float(i.p_now))
+                )
+            else:
+                projected_series.append(
+                    (now_label, now_x, float(i.p_now))
+                )
+                projected_series.append(
+                    (end_label, end_x, float(output.final_percent_high))
+                )
+        display_tz_str = _share_display_tz_label(
+            getattr(args, "_resolved_tz", None)
+        )
+        snap = _build_forecast_snapshot(
+            week_start=i.week_start_at,
+            week_end=i.week_end_at,
+            display_tz=display_tz_str,
+            version=_share_resolve_version(),
+            theme=args.theme,
+            reveal_projects=args.reveal_projects,
+            actual_series=actual_series,
+            projected_series=projected_series,
+            current_pct=float(i.p_now),
+            projected_low_pct=float(output.final_percent_low),
+            projected_high_pct=float(output.final_percent_high),
+            days_remaining=float(i.remaining_days),
+            dollars_per_percent=float(i.dollars_per_percent),
+            dollars_per_percent_source=i.dollars_per_percent_source,
+            low_conf=(i.confidence == "low"),
+        )
+        _share_render_and_emit(snap, args)
+        return 0
+
     if args.json:
         print(_emit_forecast_json(output))
         return 0
@@ -18755,6 +19254,7 @@ def _render_five_hour_blocks_table(
 
 def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
     """List API-anchored 5h blocks with rollup totals + 7d-drift columns."""
+    _share_validate_args(args)
     config = load_config()
     args._resolved_tz = resolve_display_tz(args, config)
     # Pin "now" once (CCTALLY_AS_OF for fixture-pinned harnesses; mirrors
@@ -18831,6 +19331,61 @@ def cmd_five_hour_blocks(args: argparse.Namespace) -> int:
                 d["seven_day_pct_at_block_end"] = latest_7d
             block_dicts.append(d)
 
+        # Shareable-reports gate: --format short-circuits the JSON / table
+        # dispatch via `_share_render_and_emit`. The mutex in
+        # `_add_share_args` keeps `--format` and `--json` from coexisting.
+        # Note: --breakdown is a no-op under --format (snapshot focuses on
+        # the headline 5h-block trend; per-axis sub-rows aren't in the
+        # share spec scope). Cross-reset blocks render with `▲` x-axis
+        # markers in the BarChart and `⚡` glyphs in the table cell —
+        # both signals route to the share renderer's UTF-8-safe paths.
+        # Gate runs BEFORE the optional `_load_breakdown` loop so a
+        # 50-block --format invocation doesn't pay 50 wasted SQLite
+        # queries the snapshot would discard.
+        if getattr(args, "format", None):
+            display_tz_str = _share_display_tz_label(args._resolved_tz)
+            # Period bounds: prefer the user's --since/--until filter
+            # window; fall back to oldest/newest block timestamps when no
+            # filter was applied so the period label reflects what the
+            # snapshot actually covers.
+            # block_dicts is DESC-ordered: [-1] is oldest, [0] is newest.
+            if since_iso:
+                period_start = _share_parse_date_to_dt(
+                    since_iso, args._resolved_tz,
+                )
+            elif block_dicts:
+                tail = block_dicts[-1].get("block_start_at")
+                period_start = _share_parse_date_to_dt(
+                    (tail or "").split("T")[0] or None,
+                    args._resolved_tz,
+                )
+            else:
+                period_start = _share_now_utc()
+            if until_iso:
+                period_end = _share_parse_date_to_dt(
+                    until_iso, args._resolved_tz,
+                )
+            elif block_dicts:
+                head = block_dicts[0].get("block_start_at")
+                period_end = _share_parse_date_to_dt(
+                    (head or "").split("T")[0] or None,
+                    args._resolved_tz,
+                )
+            else:
+                period_end = _share_now_utc()
+            snap = _build_five_hour_blocks_snapshot(
+                block_dicts,
+                period_start=period_start,
+                period_end=period_end,
+                display_tz=display_tz_str,
+                version=_share_resolve_version(),
+                theme=args.theme,
+                reveal_projects=args.reveal_projects,
+                tz=args._resolved_tz,
+            )
+            _share_render_and_emit(snap, args)
+            return 0
+
         # Optional breakdown.
         if args.breakdown:
             for bd in block_dicts:
@@ -19241,6 +19796,90 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
         conn.close()
 
     if not should_insert:
+        # Self-heal: a prior record-usage invocation may have inserted
+        # the snapshot but been killed (CC self-update, machine sleep,
+        # OOM) before maybe_record_milestone / maybe_update_five_hour_block
+        # could run. Pre-probe both surfaces with cheap indexed SELECTs
+        # and only invoke the helpers when a row is actually missing or
+        # stale. Steady-state cost: 1-3 SELECTs (latest snapshot always;
+        # +max_milestone if floor>=1; +block last_observed if window_key
+        # is set); ZERO JSONL re-ingest on healthy ticks. The helpers themselves are idempotent under
+        # concurrent record-usage instances (INSERT OR IGNORE for
+        # percent_milestones; SQLite write-lock serialization for the
+        # 5h upsert). Without the pre-probe, every dedup tick would
+        # trigger sync_cache + a window walk + replace-all rollups via
+        # maybe_update_five_hour_block's unconditional _compute_block_totals
+        # call. Regression: bin/cctally-record-usage-selfheal-test.
+        try:
+            heal_conn = open_db()
+            try:
+                latest_row = heal_conn.execute(
+                    "SELECT * FROM weekly_usage_snapshots "
+                    "WHERE week_start_date = ? "
+                    "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
+                    (week_start_date,),
+                ).fetchone()
+                if latest_row is None:
+                    return 0
+
+                # Probe 1: do we owe a percent milestone? Snap up before
+                # floor (status-line API returns 0.N*100 which can fall
+                # one ULP short of N — same convention as
+                # maybe_record_milestone).
+                latest_floor = math.floor(
+                    float(latest_row["weekly_percent"]) + 1e-9
+                )
+                need_milestone_heal = False
+                if latest_floor >= 1:
+                    max_existing = heal_conn.execute(
+                        "SELECT MAX(percent_threshold) AS m "
+                        "FROM percent_milestones "
+                        "WHERE week_start_date = ?",
+                        (week_start_date,),
+                    ).fetchone()
+                    if max_existing is None or max_existing["m"] is None:
+                        need_milestone_heal = True
+                    elif int(max_existing["m"]) < latest_floor:
+                        need_milestone_heal = True
+
+                # Probe 2: do we owe a 5h-block update? Either no row
+                # for this canonical window, or the existing row's
+                # last_observed_at_utc is stale relative to the latest
+                # snapshot's captured_at_utc (the kill landed between
+                # insert_usage_snapshot and maybe_update_five_hour_block).
+                need_5h_heal = False
+                window_key = latest_row["five_hour_window_key"]
+                if window_key is not None:
+                    block_row = heal_conn.execute(
+                        "SELECT last_observed_at_utc "
+                        "FROM five_hour_blocks "
+                        "WHERE five_hour_window_key = ?",
+                        (int(window_key),),
+                    ).fetchone()
+                    if block_row is None:
+                        need_5h_heal = True
+                    elif (
+                        block_row["last_observed_at_utc"]
+                        < latest_row["captured_at_utc"]
+                    ):
+                        need_5h_heal = True
+            finally:
+                heal_conn.close()
+
+            if need_milestone_heal or need_5h_heal:
+                latest_saved = _saved_dict_from_usage_row(latest_row)
+                if need_milestone_heal:
+                    try:
+                        maybe_record_milestone(latest_saved)
+                    except Exception as exc:
+                        eprint(f"[milestone] self-heal error: {exc}")
+                if need_5h_heal:
+                    try:
+                        maybe_update_five_hour_block(latest_saved)
+                    except Exception as exc:
+                        eprint(f"[5h-block] self-heal error: {exc}")
+        except Exception as exc:
+            eprint(f"[record-usage] self-heal lookup failed: {exc}")
         return 0
 
     payload = {
@@ -20430,6 +21069,44 @@ def insert_usage_snapshot(payload: dict[str, Any], week_start_name: str) -> dict
     return out
 
 
+def _saved_dict_from_usage_row(row: sqlite3.Row) -> dict[str, Any]:
+    """Mirror ``insert_usage_snapshot``'s output dict from an existing
+    weekly_usage_snapshots row. Used by ``cmd_record_usage``'s dedup
+    self-heal path so ``maybe_record_milestone`` and
+    ``maybe_update_five_hour_block`` can re-run on the latest snapshot
+    when an earlier invocation was killed between snapshot insert and
+    milestone insert (e.g. CC self-update kill window, 2026-05-08).
+
+    Field omissions match ``insert_usage_snapshot``: keys whose values
+    would be ``None`` are not emitted, so downstream ``saved.get(...)``
+    callers see the same shape they'd see on a fresh insert.
+
+    Note: ``resetText`` (the only userscript-payload-only key
+    ``insert_usage_snapshot`` re-emits in its output dict) is
+    intentionally omitted — no downstream ``saved``-dict consumer in
+    this codebase reads it. ``pageUrl`` is a column on
+    ``weekly_usage_snapshots`` but is never propagated into the output
+    dict either path.
+    """
+    out: dict[str, Any] = {
+        "id": int(row["id"]),
+        "capturedAt": row["captured_at_utc"],
+        "weekStartDate": row["week_start_date"],
+        "weekEndDate": row["week_end_date"],
+        "weeklyPercent": float(row["weekly_percent"]),
+    }
+    if row["week_start_at"] is not None:
+        out["weekStartAt"] = row["week_start_at"]
+    if row["week_end_at"] is not None:
+        out["weekEndAt"] = row["week_end_at"]
+    if row["five_hour_percent"] is not None:
+        out["fiveHourPercent"] = float(row["five_hour_percent"])
+    if row["five_hour_resets_at"] is not None:
+        out["fiveHourResetsAt"] = row["five_hour_resets_at"]
+    if row["five_hour_window_key"] is not None:
+        out["fiveHourWindowKey"] = int(row["five_hour_window_key"])
+    return out
+
 
 def _resolve_cache_report_window(
     args: argparse.Namespace,
@@ -22265,6 +22942,142 @@ def cmd_db_unskip(args: argparse.Namespace) -> int:
     return 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_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_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="cctally",
@@ -22429,9 +23242,11 @@ def build_parser() -> argparse.ArgumentParser:
         help="Project filter passed to sync-week when --sync-current is used.",
     )
     pr.add_argument(
-        "--json",
+        "--reveal-projects",
         action="store_true",
-        help="Emit machine-readable JSON output.",
+        dest="reveal_projects",
+        help="In --format output, show real project basenames instead of "
+             "the default project-1, project-2, ... anonymization.",
     )
     pr.add_argument(
         "--detail",
@@ -22443,6 +23258,7 @@ def build_parser() -> argparse.ArgumentParser:
         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(
@@ -22470,10 +23286,9 @@ def build_parser() -> argparse.ArgumentParser:
             """
         ),
     )
-    fc.add_argument("--json", action="store_true",
-                    help="Emit machine-readable JSON; suppresses terminal render.")
-    fc.add_argument("--status-line", action="store_true", dest="status_line",
-                    help="Emit one-line compact string for status-line injection.")
+    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.")
@@ -22487,6 +23302,7 @@ def build_parser() -> argparse.ArgumentParser:
                     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)
 
     pb = sub.add_parser(
@@ -23058,9 +23874,11 @@ def build_parser() -> argparse.ArgumentParser:
         help="Add per-axis rollup-child rows under each block.",
     )
     fhb.add_argument(
-        "--json",
+        "--reveal-projects",
         action="store_true",
-        help="Emit camelCase JSON (schemaVersion 1).",
+        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",
@@ -23075,6 +23893,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Display timezone: local, utc, or IANA name. "
              "Overrides config display.tz for this call.",
     )
+    _add_share_args(fhb)
     fhb.set_defaults(func=cmd_five_hour_blocks)
 
     # -- cache-sync --
@@ -23134,16 +23953,18 @@ def build_parser() -> argparse.ArgumentParser:
         help="Sort direction by date (default: asc).",
     )
     dy.add_argument(
-        "--json",
+        "--reveal-projects",
         action="store_true",
-        dest="json",
-        help="Output JSON matching upstream ccusage daily format.",
+        dest="reveal_projects",
+        help="In --format output, show real project basenames instead of "
+             "the default project-1, project-2, ... anonymization.",
     )
     dy.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(dy)
     dy.set_defaults(func=cmd_daily)
 
     # -- monthly --
@@ -23185,16 +24006,18 @@ def build_parser() -> argparse.ArgumentParser:
         help="Sort direction by month (default: asc).",
     )
     mo.add_argument(
-        "--json",
+        "--reveal-projects",
         action="store_true",
-        dest="json",
-        help="Output JSON matching upstream ccusage monthly format.",
+        dest="reveal_projects",
+        help="In --format output, show real project basenames instead of "
+             "the default project-1, project-2, ... anonymization.",
     )
     mo.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(mo)
     mo.set_defaults(func=cmd_monthly)
 
     # -- weekly --
@@ -23223,11 +24046,13 @@ def build_parser() -> argparse.ArgumentParser:
                     help="Show per-model cost breakdown sub-rows.")
     we.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
                     help="Sort direction by week (default: asc).")
-    we.add_argument("--json", action="store_true", dest="json",
-                    help="Output JSON.")
+    we.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.")
     we.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(we)
     we.set_defaults(func=cmd_weekly)
 
     # -- codex shared args helper --
@@ -23423,13 +24248,15 @@ def build_parser() -> argparse.ArgumentParser:
                            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("--json", action="store_true", dest="json",
-                           help="Emit JSON instead of table.")
+    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.")
+    _add_share_args(p_project)
     p_project.set_defaults(func=cmd_project)
 
     # -- diff --
@@ -23490,11 +24317,18 @@ def build_parser() -> argparse.ArgumentParser:
                     help="Show per-model cost breakdown sub-rows.")
     se.add_argument("-o", "--order", choices=("asc", "desc"), default="asc",
                     help="Sort direction by last activity (default: asc — earliest first).")
-    se.add_argument("--json", action="store_true", dest="json",
-                    help="Output JSON.")
+    se.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.")
+    se.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.")
     se.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(se)
     se.set_defaults(func=cmd_session)
 
     # ---- config (persisted user preferences) ----
@@ -23828,6 +24662,1544 @@ def build_parser() -> argparse.ArgumentParser:
     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_resolve_version() -> str:
+    """Source from CHANGELOG via the existing release helper. Empty string if unset.
+
+    `_release_read_latest_release_version` returns `(version, date) | None`;
+    the snapshot's `version` field carries the version string only.
+    """
+    info = _release_read_latest_release_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(
+    rows: list[dict[str, object]],
+    *,
+    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`.
+
+    `rows` is the in-memory `trend` list produced by `cmd_report` — a list
+    of dicts keyed in the existing JSON-shape camelCase
+    (`weekStartDate`, `weeklyPercent`, `weeklyCostUSD`, `dollarsPerPercent`).
+    The plan's snake_case keys (`week_start_date`, `used_pct`, `cost_usd`,
+    `dollar_per_pct`) are NOT the actual `cmd_report` data shape — see
+    Implementor 7 commit body for the deviation.
+
+    Caller MUST pass `rows` in chronological order (oldest first) so the
+    chart line trends left→right with time. `cmd_report`'s native `trend`
+    is newest-first; the gate site reverses before calling.
+
+    `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),
+    )
+    snap_rows: list = []
+    chart_pts: list = []
+    for i, r in enumerate(rows):
+        wsd = r.get("weekStartDate")
+        # `weekStartDate` is sourced from `week_ref.week_start.isoformat()`
+        # — guaranteed `str`. Empty / unparseable falls back to em-dash.
+        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.get("weeklyPercent")
+        cost_raw = r.get("weeklyCostUSD")
+        dpp_raw = r.get("dollarsPerPercent")
+        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
+    )
+    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(
+    rows: list["BucketUsage"],
+    *,
+    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`.
+
+    `rows` is the in-memory `BucketUsage` list produced by `_aggregate_daily`
+    inside `cmd_daily`. Each bucket has: `bucket` (YYYY-MM-DD date string),
+    `cost_usd`, `model_breakdowns` (list[dict] sorted by cost desc; first
+    entry is the top model).
+
+    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 → "—".
+
+    Caller MUST pass `rows` in chronological order so the BarChart bars
+    line up left-to-right with time. `_aggregate_daily` already returns
+    asc; the gate site re-sorts after `args.order == "desc"` was applied.
+
+    `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"),
+    )
+    total_cost = 0.0
+    for r in rows:
+        total_cost += float(getattr(r, "cost_usd", 0.0) or 0.0)
+
+    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(
+    rows: list["BucketUsage"],
+    *,
+    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`.
+
+    `rows` is the in-memory `BucketUsage` list produced by `_aggregate_monthly`
+    inside `cmd_monthly`. Each bucket has: `bucket` (YYYY-MM string),
+    `cost_usd`, and `model_breakdowns` (list[dict] sorted by cost desc).
+
+    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.
+
+    Caller MUST pass `rows` in chronological order so the BarChart bars line
+    up left-to-right with time. `_aggregate_monthly` already returns asc;
+    the gate site fires before the `--order desc` reversal in `cmd_monthly`.
+
+    `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="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(
+    rows: list["BucketUsage"],
+    overlay: list[tuple[float | None, float | None]],
+    *,
+    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`.
+
+    `rows` is the in-memory `BucketUsage` list produced by `_aggregate_weekly`
+    inside `cmd_weekly`; 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}`).
+
+    `overlay` is the parallel list of `(used_pct, dollars_per_pct)` tuples
+    computed by `cmd_weekly` from `weekly_usage_snapshots`. Either component
+    may be `None` for a week that has no captured snapshot yet — 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.
+
+    Caller MUST pass `rows` (and `overlay` aligned to it) in chronological
+    order so the BarChart bars line up left-to-right with time. The gate
+    site fires BEFORE the `--order desc` reversal in `cmd_weekly`.
+
+    `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_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(
+    rows: list[dict],
+    *,
+    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`.
+
+    `rows` is the list of per-block dicts produced inside
+    `cmd_five_hour_blocks` (sqlite Row converted to dict, with the
+    `__is_active` side-channel attached). Schema fields used:
+    `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 `rows` 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"),
+    )
+    # Reverse so BarChart x-axis runs oldest→newest (cmd_five_hour_blocks
+    # produces newest-first DESC); table-row order in the snapshot tracks
+    # chart order so consumer expectations align.
+    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 "—"
+        snap_rows.append(_lib_share.Row(cells={
+            "block_start": _lib_share.TextCell(block_lbl),
+            "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
+    )
+    sum_cost = sum(p.y_value for p in chart_pts)
+    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(
+    sessions: list["ClaudeSessionUsage"],
+    *,
+    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`.
+
+    `sessions` is the in-memory `ClaudeSessionUsage` list produced by
+    `_aggregate_claude_sessions` inside `cmd_session`. Each session 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 `sessions` already sorted in the desired order;
+    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(
+        sessions, 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,
+    )
+
+
+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")
+
+
 # ============================================================
 # ==== TUI ====                                              =
 # ============================================================
@@ -26276,13 +28648,22 @@ def _select_current_block_for_envelope(
     envelope convention (``current_week`` is snake_case; CLI ``--json`` is
     camelCase — separate conventions, see CLAUDE.md).
 
-    Delta is suppressed (``None``) when ``crossed_seven_day_reset == 1`` OR
-    when ``seven_day_pct_at_block_start IS NULL`` OR when
-    ``current_used_pct`` is None.
+    Delta semantics:
+      - Non-crossed block: ``current_used_pct - seven_day_pct_at_block_start``
+        (the natural "how much 7d% has changed during this 5h block" read).
+      - Crossed block (``crossed_seven_day_reset == 1``): the block straddles
+        a weekly reset, so the natural delta would be dominated by the
+        reset itself (e.g. −94pp) rather than the user's actual burn-rate.
+        Compute the POST-RESET delta instead — ``current_used_pct -
+        weekly_percent_at_first_post_reset_snapshot_in_block``. The React
+        panel prefixes this delta with ``⚡`` to show the reset crossing
+        without hiding the informative number.
+      - ``None`` only when ``current_used_pct`` is unknown OR the
+        block-start anchor is missing AND no post-reset anchor was found.
     """
     snap = conn.execute(
         """
-        SELECT five_hour_window_key
+        SELECT five_hour_window_key, week_start_at
           FROM weekly_usage_snapshots
          WHERE captured_at_utc <= ?
          ORDER BY captured_at_utc DESC, id DESC
@@ -26295,7 +28676,8 @@ def _select_current_block_for_envelope(
 
     block = conn.execute(
         """
-        SELECT block_start_at, seven_day_pct_at_block_start,
+        SELECT block_start_at, last_observed_at_utc,
+               seven_day_pct_at_block_start,
                crossed_seven_day_reset
           FROM five_hour_blocks
          WHERE five_hour_window_key = ?
@@ -26309,9 +28691,39 @@ def _select_current_block_for_envelope(
 
     crossed = bool(block["crossed_seven_day_reset"])
     p_start = block["seven_day_pct_at_block_start"]
+
+    # When the block crossed a weekly reset, recompute the delta against
+    # the first post-reset snapshot inside the block instead of the
+    # pre-reset block-start anchor. Use ``unixepoch()`` because
+    # ``block_start_at`` is host-local-tz (``+03:00``) while
+    # ``captured_at_utc`` is canonical UTC-Z; lex compares mis-order
+    # mixed-offset moments. ``snap.week_start_at`` is the latest
+    # (post-reset) week's anchor, so equality on that column scopes
+    # the lookup to the current weekly window.
+    p_anchor = p_start
+    if crossed and snap["week_start_at"] is not None:
+        post = conn.execute(
+            """
+            SELECT weekly_percent
+              FROM weekly_usage_snapshots
+             WHERE week_start_at = ?
+               AND unixepoch(captured_at_utc) >= unixepoch(?)
+               AND unixepoch(captured_at_utc) <= unixepoch(?)
+             ORDER BY captured_at_utc ASC, id ASC
+             LIMIT 1
+            """,
+            (
+                snap["week_start_at"],
+                block["block_start_at"],
+                _iso_z(now_utc),
+            ),
+        ).fetchone()
+        if post is not None and post["weekly_percent"] is not None:
+            p_anchor = float(post["weekly_percent"])
+
     delta = (
-        None if (crossed or p_start is None or current_used_pct is None)
-        else round(current_used_pct - p_start, 9)
+        None if (p_anchor is None or current_used_pct is None)
+        else round(current_used_pct - p_anchor, 9)
     )
     return {
         "block_start_at":               block["block_start_at"],