mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-11 06:30:03 +00:00
Miguel ÁngelandClaude Opus 4.8
16eb11367a
* 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>
51 lines
4.2 KiB
Markdown
51 lines
4.2 KiB
Markdown
# media-use usage dashboard (PostHog)
|
||
|
||
Reproducible definition of the media-use usage dashboard. The dashboard answers
|
||
"how much is media-use used, for what, is reuse working, and what can't it
|
||
satisfy" from the telemetry `scripts/lib/telemetry.mjs` already emits. Build it
|
||
in PostHog project **Hyperframes (356858)**; this doc is the source of truth so
|
||
it can be recreated. Local complement: `resolve --stats` (same questions, from
|
||
`.media/` + `~/.media`, no PostHog access needed).
|
||
|
||
## Identity (see `scripts/lib/telemetry.mjs`)
|
||
|
||
Events attribute to the **same PostHog person as the hyperframes CLI and studio**
|
||
— the shared install id in `~/.hyperframes/config.json` (`anonymousId`), stitched
|
||
to the HeyGen account (`$identify`, `distinct_id` = email/username) on sign-in.
|
||
Not fully anonymous by design; pseudonymous before sign-in, account-linked after.
|
||
`$ip:null`. Opt-out: `HYPERFRAMES_NO_TELEMETRY=1` / `DO_NOT_TRACK=1` (also CI, dev).
|
||
|
||
## Event catalog (verified present in-project)
|
||
|
||
Every event carries `surface: "media-use"`. Event **properties are coarse** —
|
||
never intent text, file names, or paths.
|
||
|
||
| Event | Fires on | Key properties |
|
||
| ---------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
|
||
| `media_use_resolve` | a resolve that produced/returned an asset | `type`, `source`, `provider`, `via`, `local_only`, `provider_override` |
|
||
| `media_use_resolve_miss` | a resolve that found nothing | `type`, `local_only`, `provider_override` (no intent) |
|
||
| `media_use_candidates` | `--candidates` / `--dry-run` listing | `type`, counts |
|
||
| `media_use_doctor_run` | `--doctor` | `ok`, `checks_failed`, `failed[]` |
|
||
| `media_use_compare` | `grade-compare` / `compare` | `command`, `cells`, `truncated`, `total`, `render_ready_timed_out` |
|
||
| `media_use_transcribe` · `media_use_duck` · `media_use_transcript_cut` | audio-engine ops | op-specific |
|
||
|
||
## Dashboard tiles
|
||
|
||
1. **Invocation volume** — `query-trends`, count of `media_use_resolve` over time (daily). "How much."
|
||
2. **By media type** — `media_use_resolve` broken down by `type` (bgm/sfx/image/icon/logo/voice/grade/lut). "For what."
|
||
3. **Resolve hit-rate** — trends formula: `A / (A + B)` where A = `media_use_resolve`, B = `media_use_resolve_miss`. "Is the catalog covering needs."
|
||
4. **Provider mix** — `media_use_resolve` broken down by `provider`; a second tile by `via` (`url` / `params-fallback` / `params`) to catch CDN→params LUT downgrades.
|
||
5. **Top misses** — `media_use_resolve_miss` broken down by `type` (the tuning signal — pair with local `resolve --stats`, which also shows the missed _intents_ that telemetry deliberately omits).
|
||
6. **Doctor health** — `media_use_doctor_run` broken down by `failed[]` (which dependency check fails most) + `checks_failed` distribution.
|
||
7. **Compare cost** — `media_use_compare` by `command`, plus `truncated` / `render_ready_timed_out` rates (observe before lifting the 16-cell cap).
|
||
8. **Adoption (optional)** — if the `first_run` property ships (plan U5), segment `media_use_resolve` first-run vs repeat.
|
||
|
||
## Recreate via the PostHog MCP
|
||
|
||
For each tile: `read-data-schema` to confirm the event/property, then a
|
||
`query-*` tool (`query-trends` for 1–7), then `insight-create`, then
|
||
`dashboard-create` collecting the insights. Keep names prefixed `media-use:` so
|
||
the dashboard is greppable. Cross-surface note: because identity is shared with
|
||
CLI/studio, you can also break these down by the same person across `cli_command*`
|
||
and `studio:*` events.
|