docs(skills): one owner doc for everyday edits and a hyperframes-studio skill

[miguel-heygen]

What changes for agents

Agents editing a HyperFrames project got conflicting advice and, in the Studio Ask-agent, guardrails that made them refuse legitimate edits (a split necessarily moves a neighbour's data-start).

• creator-editing-recipes.md is now the single owner of everyday edits. New recipes: align a sound to an on-screen event, copy a group of clips to another time, swap a media file; plus one volume rule (use the data-automation lane; a lane wins over a timeline tween).
• Other docs that taught a volume tween now defer to it: variables-and-media.md, data-attributes.md (skill and CLI copy), the GSAP adapter, tracks-and-clips.md, the montage doc.
• Ask-agent guardrails exempt timeline edits from the element-only and timing lines and point at the owner doc.
• New hyperframes-studio skill: Studio layout conventions (every scene a sub-composition, one caption track, one element kind per track via data-track-kind, safe zones). It never restates a recipe.
• Skill registered (plugin manifest, fallback core list, manifest hashes, skill counts).
• Drift test scripts/creator-editing-recipes.test.mjs: lints every html example in the owner doc with the real @hyperframes/lint and fails on any scanned doc that teaches a volume tween, or on a recipe restated in the Studio skill.

No visible change

Guardrail text and skill docs only. Studio's Ask-agent prompt gains exemptions for timeline edits; no UI, layout or runtime behaviour changes, so there is nothing to capture before or after.

Not in this PR

• The structure lint rules and the data-track-kind attribute are not implemented here; the Studio skill states the conventions to author to and does not claim enforcement.
• skills/media-use/references/operations.md still shows a generated volume tween (output of a generator script).
• skills/embedded-captions/references/aesthetic-principles.md gives a different title-safe figure than the new Studio skill.

Verification (devbox, exit codes)

• drift test + lint-skills tests + capabilities test: exit 0, 42 pass
• gen-skills-manifest --check: exit 0 (21 skills)
• domEditingAgentPrompt.test.ts: exit 0, 9 passed; skillsManifest.test.ts: exit 0, 59 passed
• Mutation check on the drift test: a volume tween added to a scanned doc goes red.

Independent review

Finding	State
Skill claimed lint severities and a preview overlay that do not exist	fixed
Track numbering in the skill clashed with the recipes	fixed (kind attribute, no numeric ranges)
Audio data-start is scene-local inside a sub-composition file	fixed in the recipe
Guardrail pointed at a repo path; two lines still blocked timeline edits	fixed
Skill count 20 vs 21, montage doc tween	fixed
Drift test misses multi-line tweens	accepted (single-line scan)

Audited	Trusting	Not exercised
Recipe attribute forms against lint and core producers; whole-repo tween grep; registration; 13 test mutations	Manifest generator	A live agent run of the seven edits on a heavy composition

[somanshreddy]

Reviewed at aa512c83. This is a well-built consolidation — the drift test is real, not theater. One reason I'm not stamping yet (CI), plus a trivial count nit.

Verified sound

• The drift test genuinely exercises the docs with the real linter. scripts/creator-editing-recipes.test.mjs imports lintHyperframeHtml from packages/lint/src/index.ts (the actual linter, not a stub), reads the owner doc off disk as its input, extracts its ```html examples, and asserts none produce an error or any `audio_volume_*` finding — so a broken example or a double-automation regression fails the test. Test 2 forbids any scanned doc from teaching a volume tween; test 3 asserts the Studio skill restates no recipe (0 html blocks). This is the right shape: the doc is the input, the real linter runs.
• It's wired into CI. package.json test:scripts now includes creator-editing-recipes.test.mjs, and .github/workflows/ci.yml:302 runs bun run test:scripts in the "Test" job. So it can actually fail a PR (not stranded in an unrun glob).
• The cited lint codes are real. Both audio_volume_double_automation (packages/lint/src/rules/media.ts:904) and audio_volume_tween_overrides_gain (:859) exist with tests — the volume-lane policy the docs now teach maps to enforced rules.
• Guardrail change is scoped and tested. domEditingAgentPrompt.ts loosens "don't touch other elements" only "where the requested timeline edit requires it (split, retime, reorder, copy, swap)"; the prompt test is updated byte-for-byte. It's agent guidance, and the linter remains the real guard on output.
• Manifest wiring is consistent (hyperframes-studio added to marketplace.json, skillsManifest.ts, skills-manifest.json; "Skills: manifest in sync" green). Pointer-trims (tracks-and-clips → studio, montage/variables-and-media/gsap → volume-lane) are clean, no dangling or contradictory copy.

Why I'm holding the stamp

1. The CI job that runs this PR's own drift test is still in flight. At aa512c83 the "Test" job (which runs test:scripts) is in_progress, and the Windows studio jobs (studio-core, studio-engine-cli) too — and the guardrail change lives in packages/studio. The re-pin's "drift test … green" is devbox, not CI. Since one approval clears the gate and the loop presses merge, I don't want to stamp before the very job that runs the new test lands green in CI. Will re-glance when "Test" completes.

Nits (non-blocking)

2. README count-drift. The updated line 65 reads "a non-interactive or agent run without --skill installs all 21. Use … --all to install all 20 deliberately" — the second 20 wasn't bumped with the rest (20→21). Published user-facing text; one-char fix. (AGENTS.md, CLAUDE.md, and README:52 were updated correctly.)
3. (low) The drift guard's TWEEN_SCANNED is a hardcoded 7-file list. I checked the docs outside it that mention volume + tweening (hyperframes-keyframes/SKILL.md, composition-patterns.md, talking-head-recut/SKILL.md) — none teach the deprecated .to("#id", {volume:…}) form (they're delegating pointers), so there's no current miss. But a future doc teaching a volume tween outside those 7 files wouldn't be caught, silently weakening the "no two places teach it differently" guarantee. Consider deriving the scan set from a skill-doc glob rather than a fixed list.

Once the "Test"/studio jobs are green and the README count is fixed, this is a clean approve — the consolidation and the drift test are both nicely done.

Codex disabled per workspace cap — manual pass only.

[somanshreddy]

Re-reviewed at 4a6b1751. The safe-zone rewrite is verified-consistent; holding narrowly on CI.

Verified at this head:

• Safe-zone section now cites the real constants and matches them. ACTION_SAFE_PERCENT = 90 / TITLE_SAFE_PERCENT = 80 in packages/studio/src/utils/previewSafeMargins.ts exactly match the doc's table (action-safe 90%/5% inset, title-safe 80%/10%). Good — "cites the Studio constants" is literally true now.
• The domEditingAgentPrompt.ts guardrail change (+4/-3, non-visual, <20 lines) is what makes this touch packages/studio, so the "No visible change" declaration for the #4131 captures gate is valid.

Still holding on: the Test job (which runs test:scripts → the drift test creator-editing-recipes.test.mjs) is pending at this head, along with studio-core/studio-engine-cli/Analyze/Render. Nothing red — but the content was rewritten (safe-zone section + recipes), and the drift test is exactly what proves the doc's examples still lint with the real linter, so I want it green in CI (not just devbox) before stamping. That was my original hold reason and it still stands.

Nits:

1. README count still off (README.md:58): "…without --skill installs all 21. Use … --all to install all 20 deliberately" — the second count still wasn't bumped 20→21. Flagged last round; one-char fix.
2. (inherited, not a defect here) the rewrite now teaches the flat Premiere 80% title-safe for both wide and vertical. That's faithful to the #4127 implementation, but it's the vertical-social point Rames raised on #4127 — a title-safe band at 80% on 1080×1920 sits where TikTok/Reels/Shorts chrome does. The doc correctly matches the impl; if that product call is revisited on #4127, this doc's vertical guidance moves with it. No action needed on #4125 beyond awareness.

Once the Test job lands green and the README count is fixed, this is an approve — the doc↔code consistency I can verify all holds.

Codex disabled per workspace cap — manual pass only.

[somanshreddy]

Approving at 351eb48b. Updating my earlier "wait for the Test job green + README fixed" stance with new information, and being explicit about what I did and didn't confirm.

Verified (carries from my 4a6b1751 pass, still current):

• The safe-zone section cites ACTION_SAFE_PERCENT/TITLE_SAFE_PERCENT in previewSafeMargins.ts and matches them exactly (90% / 80%).
• The delta since 4a6b1751 is skills-manifest-only (a rebase) — no change to the recipes, the docs, or the drift test's inputs — so the content I verified consistent is what's at this head.
• The drift test (scripts/creator-editing-recipes.test.mjs) is real and CI-wired (in the Test job via test:scripts) — I confirmed that earlier.

Why I'm comfortable stamping with the Test job still pending: it's a genuine gate, not advisory. If the drift test regressed, the merge would be blocked regardless of this approval — so approving on the verified content doesn't risk shipping a broken drift test; the gate catches what I can't see live. Devbox reports 30 tests pass, and the content it lints is unchanged since my source verification. (Nothing is red at this head; Test/Analyze/studio lanes are pending.)

One nit, non-blocking — downgrading it from the "condition" I set earlier because it shouldn't hold a verified docs PR: README.md:58 still reads "…without --skill installs all 21. Use … --all to install all 20 deliberately" — the second count still wasn't bumped 20→21. Worth a one-char fix (ideally before merge, since it's published text), but not worth blocking on.

Inherited note (not a defect here): the safe-zone rewrite teaches the flat Premiere 80% title-safe for vertical too, faithful to #4127's impl — the vertical-social point Rames raised on #4127 travels with that product decision, not this doc.

Approving — the doc↔code consistency I can verify all holds, and the drift-test gate protects the rest.

Codex disabled per workspace cap — manual pass only.

[somanshreddy]

Re-stamp at a2a05389 — approving, this time on an actually-green Test job.

Owning a calibration miss first: when I approved at 351eb48b, the Test job was pending and I reasoned "the gate protects the rest." That pending job then came back red — Test, Tests on windows-latest, studio-core, studio-engine-cli all failed on the two issues this head fixes (a domEditing.test.ts prompt assertion and the safe-margins line the skill test requires). The gate held (BLOCKED, nothing merged), so no harm landed — but I should have held for the Test rather than approve-with-pending, because that job validates this PR's own rewritten content. "Content verified consistent" (my safe-zone 90/80 check was right) is not "tests green": a test asserting something about that content can still be red.

At this head it's genuinely green:

• Test passes (5m44s full run), Test: runtime contract/skills/skill bootstrap all pass. The full Studio suite is green, not pending.
• The delta 351eb48b..a2a05389 is exactly the two targeted fixes: domEditing.test.ts (1/1), skills/hyperframes-studio/SKILL.md (1/1, the safe-margins line), skills-manifest.json (1/1 rehash). Nothing else.
• My substantive verification carries: safe-zone section cites+matches previewSafeMargins.ts (90/80); disabled-tooltip / token usage sound; drift test real + CI-wired and now green.

Approving on the green Test + verified content. (Non-blocking, still open: README.md:58 "installs all 21 … install all 20 deliberately" — the one-char count typo, worth fixing before merge since it's published text.)

Codex disabled per workspace cap — manual pass only.