diff --git a/docs/plans/2026-08-04-video-primitives-source-first.html b/docs/plans/2026-08-04-video-primitives-source-first.html index 463a99bba2..b5ae7e8c0f 100644 --- a/docs/plans/2026-08-04-video-primitives-source-first.html +++ b/docs/plans/2026-08-04-video-primitives-source-first.html @@ -851,6 +851,7 @@ User journey Migration First build + PostHog V1 scope @@ -1111,7 +1112,7 @@
1 · PrimitiveRender 1, 6, and 20 messages from the embedded data.
2 · InstallerMaterialize requested messages into the copied source.
3 · Smart funnelDiscover, authenticate only on selection, then resume the install.
-
4 · LearnMeasure OAuth completion, first preview, and first render before migrating primitive two.
+
4 · LearnShip the PostHog funnel contract and measure OAuth completion, first preview, and first render before migrating primitive two.
@@ -1147,6 +1148,68 @@ +
+
+

PostHog is part of the product contract.

+

+ The first primitive is not complete unless the acquisition and activation journey is observable from anonymous discovery through authenticated render. Track the funnel without collecting authored content. +

+
+ +
+
+

Required funnel events

+
    +
  • primitive_catalog_searched — a catalog query returns results.
  • +
  • primitive_catalog_result_selected — a user chooses a primitive and rank is recorded.
  • +
  • primitive_auth_started and primitive_auth_completed — OAuth begins and the suspended install resumes.
  • +
  • primitive_install_started and primitive_install_completed — source is materialized into the project.
  • +
  • primitive_preview_succeeded — the installed primitive first renders locally.
  • +
  • primitive_render_succeeded — the first final render completes.
  • +
  • Matching *_failed events use a bounded error_code, never raw exception text.
  • +
+
+
+

Identity and privacy boundary

+
    +
  • Create one funnel_id before search and preserve it across OAuth, resume, retries, and install.
  • +
  • Use the anonymous CLI installation identity before auth; on OAuth success, identify the HeyGen user and alias the anonymous journey once.
  • +
  • Attach primitive_id, catalog_version, result rank, CLI version, duration, auth state, and a deduping event or install id.
  • +
  • Never send the raw query, message text, HTML, CSS, JavaScript, asset URLs, credentials, tokens, or rendered media.
  • +
  • Honor the existing telemetry opt-out and keep event names and properties versioned and documented.
  • +
+
+
+ +
+
+

Activation funnel

+
catalog searched
+  → result selected
+  → OAuth completed
+  → install completed
+  → first preview
+  → first render
+
+ +
+ +
+

Measurement acceptance

+

+ A test journey that searches anonymously, authenticates, resumes the same selection, installs, previews, and renders must produce one ordered funnel with a stable funnel_id, correctly stitched identities, no duplicate success events, and no user-authored content in any PostHog payload. +

+
+
+

Start with one thin seam.

@@ -1161,7 +1224,7 @@
  • Let catalog install materialize user data into the copied source file.
  • Keep existing scalar variables for common Studio controls.
  • Preserve the current HyperFrames runtime, GSAP contract, lint, check, and render path.
  • -
  • Measure local query to Smart click, OAuth completion, install, and first render.
  • +
  • Ship and verify the PostHog journey from anonymous catalog search through authenticated first render.
  • @@ -1187,7 +1250,7 @@
    Source-first primitives architecture brief - Current behavior, proposed seam, migration map, and V1 scope + Current behavior, proposed seam, migration map, PostHog funnel, and V1 scope