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.

[jrusso1020]

Verified the mechanism claims at source rather than from the description. All three hold:

• Flag-less renders inherit. createRenderPlan resolves flagSkill ?? loadProjectConfig(project.dir).authoringSkill, so a render with no --skill picks up the persisted owner. Precedence is the right way round — an explicit flag still wins — and both directions are pinned by the new plan tests.
• --batch inherits. batchPath is a field on the single render plan and authoringSkill is resolved once on that same plan, so every item in a batch carries the one resolved value. No per-item gap.
• Seed-once is genuinely forward-only. seedProjectAuthoringSkill returns early on an existing stamp, and an invalid slug is dropped rather than written. Worth noting the read path normalizes too (readProjectConfig → normalizeConfig → normalizeSkillSlug), so a hand-edited garbage value can't reach telemetry and doesn't wedge the seed — the guard sees the normalized undefined and heals the stamp on the next --skill render. That interaction is easy to get wrong and it's right here.

One thing worth fixing before merge: this is the first writer that overwrites an existing hyperframes.json.

Every pre-existing writeProjectConfig call site is guarded to write only when the file is absent — init.ts behind if (!existsSync(...)), and both add.ts sites behind !hasConfig / !existsSync(projectConfigPath(...)). So until now the whole-file overwrite in writeProjectConfig was safe by construction: there was never anything on disk to lose. seedProjectAuthoringSkill breaks that invariant — it reads, normalizes, and rewrites a file the user already has, on the first render --skill in any existing project.

The problem is the round-trip. normalizeConfig builds its result from an explicit whitelist — $schema, registry, paths.{blocks,components,assets}, media.autoProxy, authoringSkill — with no ...partial spread, and writeProjectConfig replaces the file wholesale. So the seed writes back only what the whitelist knows about.

Being precise about severity, because it splits in two:

• Immediate, every affected project: the render rewrites key order and materializes a media: { autoProxy: ... } block into projects that never had one. hyperframes.json is normally committed, so users get a config diff they didn't ask for, produced as a side effect of rendering rather than by any config command. Cosmetic, but surprising in exactly the way that generates bug reports.
• Latent, and the reason I'd fix it now: any key outside the whitelist is silently dropped. That's no loss for a strictly conforming config today, but it makes the seed a standing hazard as the schema grows — and this PR is itself extending the schema. A field added in a later version gets deleted by any render running a CLI that predates it, silently, on a file under version control.

The fix keeps the seed surgical: read and parse the raw JSON, set authoringSkill on it, write it back, rather than round-tripping through normalizeConfig. Then unknown keys and existing formatting survive, and the only delta is the key you meant to add. The try/catch best-effort posture and the seed-once guard both stay as they are.

One claim I did not verify: the 77–96% weekly-attribution-gap figure is telemetry-side and not checkable from the diff, so I'm taking it as given rather than confirming it. The code change is consistent with closing that class of gap regardless of the exact magnitude.

Approving — the write-path change above is a small, contained follow-up and everything else here is clean. CI is fully green at ed1927e. Leaving the deeper attribution-chain pass to the parallel review rather than duplicating it.

— Rames Jusso

[miga-heygen]

SSOT -- Single Resolution Chain, Correct Seed-Once

The attribution resolution is clean: ONE chain, no forks.

explicit --skill flag  →  persisted authoringSkill in hyperframes.json  →  undefined

In plan.ts:

const flagSkill = normalizeSkillSlug(args.skill);
const authoringSkill = flagSkill ?? loadProjectConfig(project.dir).authoringSkill;

No second copy of this decision exists anywhere in the codebase. normalizeSkillSlug is the single gate for all slug input — init, render, and config read all funnel through it. The regex matches the JSON Schema pattern in docs/schema/hyperframes.json exactly: ^[a-z0-9][a-z0-9-]{0,63}$.

Seed-once semantics — verified

Scenario	Expected	Actual
init --skill=X	Stamps config	scaffoldProject spreads { ...DEFAULT_PROJECT_CONFIG, authoringSkill: skill } ✓
render --skill=X (no existing stamp)	Seeds config, uses X	seedProjectAuthoringSkill sees !current?.authoringSkill, writes ✓
render --skill=X (existing stamp Y)	Does NOT overwrite, uses X	Early return on truthy authoringSkill; plan uses flagSkill ✓
render (no flag, existing stamp Y)	Uses Y	Falls back to loadProjectConfig().authoringSkill ✓
render (no flag, no config)	No attribution	Both paths return undefined ✓

The ordering in render.ts is correct: createRenderPlan resolves the plan's authoringSkill for THIS render first, THEN seedProjectAuthoringSkill persists for future renders.

Creation workflow coverage

All init-using workflows now pass --skill: embedded-captions, faceless-explainer, general-video, motion-graphics, music-to-video, pr-to-video, product-launch-video. website-to-video and graphic-overlays don't use hyperframes init — appears intentional.

Schema

authoringSkill properly added as top-level field. additionalProperties: false on the root means this addition is required for validation. Covered.

Standards

No bare as T in production code. No non-null assertions. rawSkill: unknown is the correct widening. normalizeSkillSlug is reused at all 4 call sites — no duplicated validation.

CI

All 44 checks pass.

---

Finding: seedProjectAuthoringSkill lossy round-trip via normalizeConfig

Converges with Rames's review — this is real and worth fixing before merge.

seedProjectAuthoringSkill reads the existing config, runs it through normalizeConfig, sets authoringSkill, and writes the result back. normalizeConfig builds from an explicit field whitelist (no rest-spread), so the round-trip is lossy:

1. Immediate: The render rewrites key order and materializes a media block into projects that never had one. hyperframes.json is normally committed, so users get a config diff they didn't ask for — caused by a render, not a config command.
2. Latent: Any key outside the whitelist is silently dropped. No loss for a conforming config today, but it's a standing hazard as the schema grows. A field added by a newer CLI version gets deleted by any render on an older CLI that predates it.

Fix: In the seed path, parse the raw JSON, set authoringSkill on the parsed object, write it back — bypass normalizeConfig entirely. Unknown keys and formatting survive, and the only delta is the key you meant to add.

Verdict

The attribution chain, seed-once semantics, and test coverage are all solid. Fix the lossy normalizeConfig round-trip in the seed path, then ship it.

— Miga

[WaterrrForever]

Good catch — you were both right, and the whitelist rebuild was worse than cosmetic. Fixed in f10cb5d0d.

Reproduced it first to pin the severity. Given a hand-written config:

{
  "registry": "https://example.com/my-registry",
  "paths": { "blocks": "src/blocks", "components": "src/fx", "assets": "media" },
  "myTeamSetting": { "reviewer": "wenbo", "keep": true },
  "futureSchemaKey": 42
}

one flag-less render silently deleted myTeamSetting and futureSchemaKey, and added $schema + media. So the latent hazard is already live for anyone with a key we do not know about, not only for future schema growth.

Rames — your framing of the broken invariant was the useful part: I had not noticed that every other writeProjectConfig call site is absence-guarded (init.ts:599, add.ts:160, add.ts:309), which is exactly what made whole-file overwrite safe until this seed. Verified all three before changing anything.

Fix is your prescription: parse the raw JSON, set authoringSkill, write it back, bypassing normalizeConfig. Two things on top:

• Indentation is reused (/\n([ \t]+)"/ off the source text) rather than hardcoded to 2 spaces, so a 4-space or tab-indented file is not reflowed.
• A corrupt config is now left untouched. Previously readProjectConfig returned undefined for unparseable JSON and the seed wrote a fresh default over it — a render clobbering a file the user was mid-edit on. It now returns early.

On a real init-written config the diff is exactly the added key. One residual I should name rather than let you find: JSON.parse → JSON.stringify expands a hand-inlined nested object across lines, so a config with { "a": 1 } on one line reflows even though every key survives. Inherent to the parse/write-back approach; byte-exactness would need a surgical text insert, which I judged more fragile than the reflow is annoying. Say the word if you disagree.

Seed-once semantics unchanged, including the normalize interaction you called out — a garbage slug still neither reaches telemetry nor wedges the seed.

4 regression tests added, all locking the failure mode rather than the fix: unknown keys survive, no media/$schema materialization, indentation reused, corrupt config untouched. 43/43 passing in projectConfig + plan + skill.

Miga — that leaves your deep attribution-chain pass as the only thing outstanding from my side; happy to hold for it.

And noted on the 77–96%: correct to take as given, it is not derivable from the diff. It is countIf(notEmpty(authoring_skill)) / count() over real-human render_complete per week on PostHog 356858 — 96.0 / 89.8 / 77.3 / 86.5 for 06-28 → 07-19. Query is in the doc if anyone wants to re-run it independently.

Addressed in f10cb5d — seed now patches raw JSON in place.

[miga-heygen]

Re-review — normalizeConfig round-trip fixed

The new commit (f10cb5d0) addresses the blocking finding cleanly:

1. No more lossy round-trip: Seed now parses raw JSON, sets authoringSkill on the parsed object, writes back. Unknown keys survive. ✓
2. No materialized defaults: Only authoringSkill is added — no media block, no $schema, no key reordering. ✓
3. Indentation preserved: Detects the file's own indent from existing content (/ ([ ]+)"/). ✓
4. Corrupt config guarded: Non-object, null, or array configs leave the file untouched (early return, not a clobber). ✓
5. New-file path preserved: When no file exists, still uses writeProjectConfig with DEFAULT_PROJECT_CONFIG — correct, nothing to preserve. ✓
6. as Record<string, unknown>: Behind a proper type guard (!== null && typeof === "object" && !Array.isArray). Valid. ✓

Four new tests directly lock down the exact issues Rames and I flagged: unknown keys preserved, no media block materialization, indentation reuse, corrupt config untouched. Thorough.

CI note

CodeQL flags existsSync → readFileSync as a TOCTOU race (projectConfig.ts:184). The catch block makes this safe in practice (file disappears between check and read → readFileSync throws → catch swallows → seed skipped → render unaffected). If you want to silence it cleanly: drop the existsSync, try readFileSync directly, catch ENOENT to fall through to the write-new-file path.

Windows tests still in progress at review time. 43/45 checks pass.

Ship it once CI clears.

— Miga

[jrusso1020]

Re-reviewed at f10cb5d0. The write-path issue is fixed properly, and the fix is tighter than what I asked for.

The lossy rewrite is gone. The seed now patches the parsed JSON in place instead of round-tripping through normalizeConfig, so unknown keys survive, no defaults get materialized into a file the user never wrote, existing key order is preserved with the new key appended last, and the file's own indentation is reused. Two cases I didn't ask for and am glad to see handled: a non-object top-level JSON value (a valid JSON array or scalar) returns early rather than having a property stapled onto it, and a corrupt file is left byte-exact rather than clobbered by a render.

The four new tests are real enforcement, not comments that assert a guarantee. Each one fails if the normalizer round-trip comes back: preserves config keys outside the known schema loses myTeamSetting/futureSchemaKey, does not materialize a media block pins the exact key set and order via Object.keys(...)).toEqual([...]), the indentation test pins 4-space input, and the corrupt-config test asserts the original bytes. That's the distinction that matters, and these are on the right side of it.

The subtle thing that survived the rewrite: the seed-once guard still normalizes what it reads (normalizeSkillSlug(raw.authoringSkill)) rather than testing the raw value for truthiness. So a hand-edited garbage slug still neither reaches telemetry nor wedges the seed permanently, and the next --skill render heals the stamp. Switching to raw-JSON access is exactly where that behavior would have been easy to drop by accident.

One new item, non-gating. The added existsSync(path) followed by readFileSync(path) trips CodeQL's file-system-race rule at the seed, and that scan is now red where it was green before this commit. The practical impact is nil: a delete inside that window throws ENOENT straight into the existing catch, so attribution is skipped and the render is unaffected, and this is the user's own project directory with no privilege boundary in play. But rather than annotate around it, the rule's own recommendation is to not check-then-use. Dropping existsSync and letting a single readFileSync throw, treating ENOENT as "no config yet" and falling through to the create path, collapses it to one filesystem operation and clears the alert in about two lines.

Worth being precise that this does not block: CodeQL is not among the required status checks, and all eight that are required are green at this head.

One trivial edge, purely for completeness. The indent probe falls back to two spaces when there's no \n<indent>" match, so a single-line or minified config would come back pretty-printed. That's strictly better than the previous behavior and vanishingly unlikely for a generated file, so I'd leave it alone.

Approving. Nice, contained fix.

— Rames Jusso

[miguel-heygen]

Re-review at exact head f10cb5d0dfc57052467aab45d695c0eea4889a2f.

Audited: the ed1927e → f10cb5d0 delta in packages/cli/src/utils/projectConfig.ts and projectConfig.test.ts end-to-end, plus current required-check rules/status.

Trusting: the unchanged attribution-chain/schema/skill-callsite surface to the prior Rames + Miga passes; I re-checked its integration points into this seed path.

The lossy round-trip blocker is closed:

• seedProjectAuthoringSkill now parses and patches the raw object, preserving unknown keys, original key order, and absence of defaults instead of rebuilding through normalizeConfig.
• Non-object/corrupt configs remain untouched; fresh configs still take the normal default-config writer path.
• The seed-once guard still normalizes the existing slug, so an invalid hand edit cannot reach telemetry or permanently wedge later healing.
• The four new tests pin the actual failure modes: unknown-key survival, exact non-materialized key set/order, indentation reuse, and byte-preserved corrupt input.

Non-blocking CI note: CodeQL is the sole red check, and the repository ruleset confirms it is not one of the eight required contexts; the PR is correctly MERGEABLE / UNSTABLE, not CI-blocked. Its existsSync → readFileSync alert can be silenced by trying the read directly and handling absence, while the current catch already preserves the best-effort render contract.

Verdict: APPROVE

Reasoning: The existing-config writer is now surgical and regression-pinned, the attribution semantics remain intact, and every required status check is green at this exact head.

— Magi