docs(contributing): refresh the catalog contribution guide

[miguel-heygen]

What

Rewrites docs/contributing/catalog.mdx. The page had drifted from the repo on facts, commands, and gaps.

Corrections (each verified against the repo, not the live site):

Page said	Actually
"52 blocks and counting"	113 blocks, 25 components
Quick version: hyperframes lint + validate	validate is a deprecated alias that prints a notice; check is the gate
"A block is two files"	Components need three. demo.html is required
"External contributors attach the preview MP4"	CI renders the PNG and MP4 for every changed registry item
Gaps: karaoke sweep, podcast lower thirds, news ticker, route maps	All shipped

Additions:

• params documented, with the sample and the four types. Declaring them opens a live customization panel in Studio when the block is added. 6 of 113 blocks use it today, which is a direct consequence of no contributor-facing doc ever mentioning the field.
• The other optional registry-item.json fields in a short table (author, relatedSkill, registryDependencies, license, sourcePrompt, minCliVersion, deprecated).
• Quality bar picks up the 64-72px monospace caption floor and the fitTextFontSize() requirement, both of which only existed in the skill reference.
• A motion-review section: five rules, each paired with the question you ask yourself against the rendered preview. Passing check is not the same as the motion being good, and nothing in the guide covered that.
• A "what to write in the PR body" note asking for when-to-use, duration range, and known pitfalls. A one-line description says what a block looks like, not when to reach for it, and that is what decides whether it gets used.

"What's Needed Right Now" is re-sorted by the job a shot does in a video rather than by technique. The registry has 29 transitions and 33 code blocks against 2 openings, 1 outro, and zero blocks for beat-driven cuts, interaction demos, or data readouts, which is the actual shape of the gap.

Why

The page is the entry point for external contributors. Every stale line in it costs a contributor a failed run: validate prints a deprecation notice, a component without demo.html fails catalog CI with no explanation on this page, and four of the nine listed gaps have already shipped, so a first-time contributor following the list builds a duplicate.

How

Docs-only, single file. No schema change and no code change, so the when-to-use / pitfalls guidance is a PR-body convention rather than a new field.

Counts and behaviors were read from registry/, packages/core/src/registry/types.ts, packages/cli/src/commands/validate.ts, scripts/generate-catalog-previews.ts, and .github/workflows/catalog-previews.yml.

Not covered here, deliberately:

• scripts/generate-catalog-pages.ts renders author and relatedSkill but drops params, so a block's customization surface is invisible on its catalog page. Real gap, needs a code change, separate PR.
• Backfilling params onto the 107 blocks that lack them.
• skills/hyperframes-registry/references/contributing.md overlaps this page and is more accurate in places. Leaving the consolidation for its own change.

Test plan

• Unit tests added/updated
• Manual testing performed
• Documentation updated (if applicable)

Docs-only change. Verified every count and command claim against the repo at 411ada0d9; lefthook pre-commit (format, lint, tracked-artifacts, largefiles, commitlint) green.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Aug 2, 2026, 7:44 PM

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