feat(media-use): usage visibility — shared telemetry identity, miss log, resolve --stats (#2113)

* feat(media-use): usage visibility — shared telemetry identity, miss log, resolve --stats

- U6: join the CLI/studio telemetry identity — read the shared install id from
  ~/.hyperframes/config.json (seed if absent) instead of a media-use-only
  ~/.media/anon-id, and $identify to the HeyGen account (email/username) once
  per run on sign-in. One PostHog person across surfaces; pseudonymous before
  sign-in, account-linked after. Event properties stay coarse (no intent/paths).
- U1: one-time first-run disclosure to stderr + Privacy section in SKILL.md;
  honors DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY.
- U2: persist resolve misses to ~/.media/misses.jsonl (local → intent kept;
  the media_use_resolve_miss telemetry event stays intent-free).
- U3: `resolve --stats` (+ --days) — local usage report over .media/ + ~/.media
  (volume by type, source/provider/via split, hit-rate, top missed intents,
  global-cache size/reuse); human + --json.
- U4: reproducible PostHog dashboard definition (references/telemetry-dashboard.md).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(media-use): address #2113 review — shared notice state, legacy id migration, stats robustness

- Notice-shown state now lives in the shared ~/.hyperframes/config.json
  (config.telemetryNoticeShown, the CLI's own field) instead of a media-use-only
  ~/.media marker — so shared-identity users see the first-run notice once per
  person, not once per tool.
- Migrate a pre-existing ~/.media/anon-id into the shared config on upgrade, so
  media-use-only users keep their PostHog persona instead of resetting.
- buildStats: --days only windows on a positive finite value (negative/NaN → all
  time, not an empty report); dropped the top-level catch that masked a real
  error as an all-zero "no usage" report (sub-reads are individually guarded).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

skills/media-use/SKILL.md

@@ -135,6 +135,8 @@ node <SKILL_DIR>/scripts/resolve.mjs --type lut --intent "teal orange blockbuste
 | `--provider`    | Force one generator (e.g. `codex`, `mflux`, `kokoro`, `heygen`)                      |
 | `--adopt`       | Bulk-import existing assets/ into manifest                                           |
 | `--doctor`      | Check local CLI dependencies; no manifest changes                                    |
+| `--stats`       | Print local usage stats from `.media/` and `~/.media`; no manifest changes           |
+| `--days N`      | Limit `--stats` to timestamped records/misses from the last N days                   |
 | `--json`        | Output JSON instead of one-line result                                               |
 
 ## Reuse before you resolve
@@ -316,11 +318,24 @@ Assets are cached automatically on resolve. Every resolved/ingested asset is aut
 
 For a _semantically_ similar (not identical) need in another project, the exact-match floor won't fire — use [Reuse before you resolve](#reuse-before-you-resolve): `--candidates` lists the global assets, and `--reuse <sha>` imports the one you pick. This is how a track resolved in one project gets reused in the next when the wording differs.
 
+## Usage stats
+
+Use `resolve --stats` for a local, shareable report over the current project's `.media/` manifest, the global `~/.media/` cache, and local resolve misses. Human output is compact; add `--json` for a single machine-readable object, and `--days N` to window timestamped records.
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --stats --project . --days 7
+# media-use stats
+# total resolves: 12
+# misses: 2
+# hit rate: 86%
+```
+
 ## Files
 
 - `.media/manifest.jsonl`: machine SSOT, one JSON record per line
 - `.media/index.md`: agent-readable table (id, type, dur, dims, path, description)
 - `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)
+- `~/.media/misses.jsonl`: local-only resolve misses, including intent text for `--stats`
 
 ## Audio engine: voiceover, music, SFX, captions, transcription
 
@@ -389,3 +404,12 @@ resolve never waits on or fails from telemetry).
 
 Opt out with `DO_NOT_TRACK=1` or `HYPERFRAMES_NO_TELEMETRY=1` (also off in CI and
 dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
+
+## Privacy
+
+media-use uses the same shared install id as the `hyperframes` CLI/studio
+(`~/.hyperframes/config.json`). When you are signed in to HeyGen, usage is
+linked to your account email, or username when email is unavailable, matching
+the CLI behavior. The events stay coarse: media type, source, provider, and
+small counts only; intent text and paths stay local. Disable telemetry with
+`HYPERFRAMES_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.