fix(cli): persist authoring skill in hyperframes.json for durable render attribution

[WaterrrForever]

Summary

The "Skills penetration" tile on the growth dashboard looked like it dropped week-over-week. It's not a skills regression — authoring_skill telemetry is structurally incomplete. Today it's stamped only on the first render that goes through a workflow passing --skill, so re-renders, npm run render, --batch, existing-project renders, and general-video lose it or never had it. Across recent weeks 77–96% of every week's real-human render volume carries no attribution, which pins the (render-weighted) metric in the single digits and makes it swing on batch/re-render volume.

This makes attribution durable: the owning skill is persisted once in the project's hyperframes.json, and every later render inherits it without re-passing --skill.

Root cause

authoring_skill (packages/cli/src/telemetry/events.ts) is derived solely from the --skill flag in createRenderPlan (packages/cli/src/commands/render/plan.ts). Nothing persisted it, so attribution was lost on the highest-volume paths:

• re-renders, the scaffolded npm run render wrapper (packages/cli/src/commands/init.ts), and --batch never re-pass the flag;
• existing-project renders deliberately skip workflow routing and go through hyperframes-cli (skills/hyperframes/SKILL.md), whose render examples omit --skill;
• general-video never passed --skill at all.

Verified against PostHog (project 356858): high-volume installs are overwhelmingly 0%-attributed, and the 07-12 → 07-19 "drop" is a partial current week plus a ~4× surge in distinct rendering installs (a broad long tail, not a few whales) — not a regression.

Fix

Persist the owning skill in hyperframes.json (ProjectConfig.authoringSkill):

• hyperframes init --skill=<slug> stamps it into the project config at creation.
• hyperframes render resolves the explicit --skill flag → else the persisted value, so flag-less re-renders / --batch / npm run render stay attributed to the workflow that created the project.
• An explicit --skill on render seeds the stamp — seed-once: it never overwrites an existing owner (a one-off --skill still governs that render's telemetry but does not rewrite the project's identity).
• All render-producing creation workflows now declare their skill on their init call.

init --skill=X   ─────────────────────────────► hyperframes.json.authoringSkill = X  (seed-once)
render --skill=X ──► authoring_skill=X ─(seed)──►            │
render           ───────────────────────────────────────────┘  ► authoring_skill inherited on every later render

Test plan / Validation

• packages/cli/src/utils/projectConfig.test.ts — +6 tests (slug-gate on read, seed-once, create-if-missing, preserves other config fields)
• packages/cli/src/commands/render/plan.test.ts — +2 tests (flag-less render inherits the persisted stamp; explicit --skill overrides it)
• 39/39 unit tests pass across projectConfig + skill + render-plan suites
• oxlint and oxfmt clean on all changed files; tsc --noEmit clean on all changed files
• docs/schema/hyperframes.json updated (schema is additionalProperties:false, so the new field is required there)

Scope / limitations

• Forward-only, not retroactive — historical telemetry is unchanged; attribution completeness improves as the new CLI propagates (scaffolded projects pin a CLI version, so it is gradual).
• slideshow is intentionally out of scope: it outputs a present deck / snapshot stills, never an MP4, so it emits no render_complete. Domain skills (hyperframes-core, media-use, …) are correctly not counted — they are building blocks, not authoring workflows.
• Separate follow-up, not in this PR (PostHog-side, not code): the tile is render-weighted, which is dominated by batch/re-render volume regardless of attribution completeness. A user-weighted penetration ("% of weekly rendering users who used ≥1 skill") is robust to that. On current data it reads 6.7% → 9.5% → 19.4% (completed weeks) vs the render-weighted 2.0% → 3.1% → 9.8%.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jul 24, 2026, 12:53 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.