diff --git a/docs/contributing/catalog.mdx b/docs/contributing/catalog.mdx
new file mode 100644
index 000000000..e060a8328
--- /dev/null
+++ b/docs/contributing/catalog.mdx
@@ -0,0 +1,186 @@
+---
+title: Contributing to the Catalog
+description: How to add blocks and components to the HyperFrames registry.
+---
+
+Your agent already knows how to build video components. It writes HTML. HyperFrames renders it. The registry is the collection of everything that's been built — 52 blocks and counting.
+
+This guide shows you how to add to it.
+
+
+**Quick version** — Fork the repo. Write one HTML file with a paused GSAP timeline. Add `registry-item.json`. Run `hyperframes lint` + `validate`. Publish with `npx hyperframes publish`. Open a PR.
+
+
+## Why Contribute?
+
+Every block in the registry exists because someone needed it and built it. When you add a block, every HyperFrames user gets it with one command:
+
+```bash
+npx hyperframes add instagram-follow
+```
+
+The registry grows, HyperFrames gets more useful, and your work ships to everyone.
+
+## Two Paths
+
+### Ideas (No Code)
+
+You spot visual trends before anyone. That's the most valuable contribution.
+
+- Screen-record a caption style from TikTok/YouTube that doesn't exist yet
+- Sketch a lower-third in Figma with fonts, colors, and timing
+- Install a component, preview it, report what feels off
+
+Open an issue on [GitHub](https://github.com/heygen-com/hyperframes/issues) with a visual reference. Tag it `component-request`.
+
+The bar for ideas is low. We'd rather have 100 and build the best 10.
+
+### Build It
+
+Every block is a single HTML file. No build step, no framework.
+
+If you use Claude Code with HyperFrames skills:
+
+> "I want to contribute a new transition that looks like \[description\]"
+
+The `/contribute-catalog` skill scaffolds the structure, validates, renders a preview, publishes to [hyperframes.dev](https://hyperframes.dev), and prepares the PR.
+
+## What Goes in the Registry
+
+**Blocks** (`registry/blocks/`) — full standalone compositions. Fixed dimensions, fixed duration. Caption styles, VFX effects, title cards, transitions.
+
+**Components** (`registry/components/`) — reusable snippets. No fixed size. CSS effects, text treatments, overlays that adapt to any composition.
+
+### Structure
+
+```
+registry/blocks/my-block/
+ my-block.html ← the composition
+ registry-item.json ← metadata
+```
+
+### registry-item.json
+
+```json
+{
+ "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+ "name": "my-block",
+ "type": "hyperframes:block",
+ "title": "My Block",
+ "description": "What this block does in one sentence",
+ "tags": ["category", "subcategory"],
+ "dimensions": { "width": 1920, "height": 1080 },
+ "duration": 5,
+ "files": [
+ {
+ "path": "my-block.html",
+ "target": "compositions/my-block.html",
+ "type": "hyperframes:composition"
+ }
+ ]
+}
+```
+
+## The Rules
+
+Five things that must be true for every registry item:
+
+
+
+ No `Math.random()`, no `Date.now()`. Use seeded PRNG only.
+
+
+ `gsap.timeline({ paused: true })`. The player controls playback.
+
+
+ `window.__timelines["id"]` must match `data-composition-id`.
+
+
+ Use `tl.eventCallback("onUpdate", render)` for Three.js/WebGL scenes.
+
+
+ `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` — no lingering text.
+
+
+
+
+Break any of these and renders won't be reproducible. The renderer captures every frame by seeking the timeline — if your animation depends on real time or random state, it breaks.
+
+
+## Quality Bar
+
+Not everything belongs in the registry. The bar is production quality.
+
+| Type | Minimum standard |
+|------|-----------------|
+| Captions | 96px+ font, text-stroke/shadow, overflow prevention |
+| VFX | Solves a problem that takes 4+ hours from scratch |
+| Transitions | Smoother than CSS — if opacity 0→1 works, it's not a transition |
+| Blocks | Would a professional use this in a client project? |
+
+### Common rejection reasons
+
+1. **"Looks like a demo"** — a spinning cube is not a component
+2. **"Text unreadable"** — font too small, no contrast treatment
+3. **"Non-deterministic"** — `Math.random()` or `Date.now()`
+4. **"Timeline not found"** — ID mismatch between HTML and JS
+5. **"Breaks as sub-composition"** — element IDs collide (prefix everything)
+
+## Workflow
+
+
+
+ Fork [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) and create your block directory:
+ ```bash
+ mkdir -p registry/blocks/your-block
+ ```
+
+
+ Create the HTML composition and `registry-item.json`. Use the templates above.
+
+
+ ```bash
+ hyperframes lint
+ hyperframes validate
+ npx oxfmt your-block.html
+ ```
+
+
+ ```bash
+ # Add to registry index
+ # Update registry/registry.json
+ npx tsx scripts/generate-catalog-pages.ts
+ ```
+
+
+ ```bash
+ hyperframes render -o preview.mp4
+ ```
+
+
+ ```bash
+ npx hyperframes publish
+ ```
+ Open a PR with your [hyperframes.dev](https://hyperframes.dev) preview link.
+
+
+
+**External contributors:** attach the preview MP4 to your PR. A maintainer handles the catalog image.
+
+**HeyGen internal:** run `scripts/upload-docs-images.sh` to push catalog PNGs.
+
+## What's Needed Right Now
+
+These are gaps in the registry. If you're looking for something to build, start here.
+
+| Category | Gap | Difficulty |
+|----------|-----|-----------|
+| Captions | Karaoke with clip-path sweep (CapCut style) | Medium |
+| Captions | RTL language layouts (Arabic, Hebrew) | Medium |
+| Lower thirds | 10 variations for podcasts/interviews | Easy |
+| Lower thirds | News ticker / scrolling text bar | Easy |
+| Maps | Animated route maps, region highlights, location pins | Medium |
+| VFX | Product turntable with HDRI | Hard |
+| VFX | Particle system with physics (collisions, gravity) | Hard |
+| Transitions | Morphing shape transitions | Hard |
+| Data viz | Sankey / flow diagrams | Medium |
diff --git a/docs/docs.json b/docs/docs.json
index 025e5600b..5c9452580 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -219,6 +219,7 @@
"group": "Contributing",
"pages": [
"contributing",
+ "contributing/catalog",
"contributing/release-channels",
"contributing/testing-local-changes"
]
diff --git a/skills/contribute-catalog/SKILL.md b/skills/contribute-catalog/SKILL.md
new file mode 100644
index 000000000..db570cff8
--- /dev/null
+++ b/skills/contribute-catalog/SKILL.md
@@ -0,0 +1,211 @@
+---
+name: contribute-catalog
+description: Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.
+---
+
+# Contribute to HyperFrames Registry
+
+Guide the user from idea to merged PR for a new registry block or component.
+
+## Workflow
+
+```
+1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
+```
+
+### Step 1: Clarify
+
+Ask what they're building. The registry has two item types:
+
+- **Block** (`registry/blocks/`, type `hyperframes:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
+- **Component** (`registry/components/`, type `hyperframes:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.
+
+Then ask:
+
+- One-sentence description of the effect
+- Visual reference (URL, screenshot, or description)
+- Who uses this and when?
+
+### Step 2: Scaffold
+
+Create the registry structure:
+
+**For blocks:**
+
+```
+registry/blocks/{block-name}/
+ {block-name}.html
+ registry-item.json
+```
+
+**For components:**
+
+```
+registry/components/{component-name}/
+ {component-name}.html
+ registry-item.json
+```
+
+**Naming convention:**
+
+| Item name | ID prefix | Example IDs |
+| ---------------- | --------- | ---------------------- |
+| `cap-hormozi` | `hz` | `hz-cg-0`, `hz-cw-3` |
+| `cap-typewriter` | `tw` | `tw-cg-0`, `tw-ch-0-5` |
+| `vfx-chrome` | `vc` | `vc-canvas` |
+
+Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.
+
+**registry-item.json for blocks:**
+
+```json
+{
+ "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+ "name": "{block-name}",
+ "type": "hyperframes:block",
+ "title": "{Human Title}",
+ "description": "{one sentence}",
+ "dimensions": { "width": 1920, "height": 1080 }, // adjust: 1080x1920 for portrait/social
+ "duration": 10, // adjust for your composition
+ "tags": ["{category}", "{subcategory}"],
+ "files": [
+ {
+ "path": "{block-name}.html",
+ "target": "compositions/{block-name}.html",
+ "type": "hyperframes:composition"
+ }
+ ]
+}
+```
+
+**registry-item.json for components** (no `dimensions` or `duration`):
+
+```json
+{
+ "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+ "name": "{component-name}",
+ "type": "hyperframes:component",
+ "title": "{Human Title}",
+ "description": "{one sentence}",
+ "tags": ["{category}"],
+ "files": [
+ {
+ "path": "{component-name}.html",
+ "target": "compositions/components/{component-name}.html",
+ "type": "hyperframes:snippet"
+ }
+ ]
+}
+```
+
+### Step 3: Build
+
+Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.
+
+#### Caption blocks
+
+**Non-negotiable caption rules:**
+
+- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).
+- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`
+- Overflow: call `window.__hyperframes.fitTextFontSize()` on every group
+- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`
+- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group
+- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.
+
+**Per-character animation** (typewriter, scramble):
+
+- Wrap each character in `` with ID `{prefix}-ch-{group}-{char}`
+- Stagger via `tl.set` at computed intervals from word timestamps
+- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)
+
+**Positioning variants:**
+
+- Centered: `display: flex; align-items: center; justify-content: center;`
+- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
+- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`
+
+#### VFX blocks (Three.js)
+
+- Use `three@0.147.0` from CDN (global script)
+- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
+- State proxy pattern: GSAP animates plain JS object, render function reads it
+- Seeded PRNG (`mulberry32`) for randomness
+
+#### All types
+
+- `data-composition-id` MUST match `window.__timelines["id"]`
+- All element IDs prefixed with block abbreviation
+- `gsap.timeline({ paused: true })` — always paused
+- No `Math.random()`, no `Date.now()`
+
+### Step 4: Validate
+
+```bash
+hyperframes lint # 0 errors required
+hyperframes validate --no-contrast # 0 console errors required
+```
+
+### Step 5: Preview
+
+```bash
+# Render preview video
+hyperframes render -o preview.mp4
+
+# Snapshot for visual QA
+hyperframes snapshot --at "1.0,3.0,5.0,7.0"
+
+# Publish to hyperframes.dev for review
+npx hyperframes publish
+```
+
+**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:
+
+- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
+- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.
+
+### Step 6: Ship
+
+**All steps are required. Missing any one produces a broken catalog entry.**
+
+`{kind}` is `blocks` or `components` depending on what you built in Step 1.
+
+```bash
+# 1. Create branch
+git checkout -b feat/registry-{name}
+
+# 2. Format HTML
+npx oxfmt registry/{kind}/{name}/*.html
+
+# 3. Update registry/registry.json — add entry to the "items" array:
+# { "name": "{name}", "type": "hyperframes:block" } (or "hyperframes:component")
+
+# 4. Generate catalog docs page
+npx tsx scripts/generate-catalog-pages.ts
+
+# 5. Publish to hyperframes.dev so reviewers can preview
+npx hyperframes publish
+
+# 6. Stage everything
+git add registry/{kind}/{name}/ registry/registry.json docs/catalog/
+
+# 7. Commit
+git commit -m "feat(registry): add {name} — {one sentence}"
+
+# 8. Push and open PR with hyperframes.dev link
+git push origin feat/registry-{name}
+gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
+```
+
+**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.
+
+## Quality Gate
+
+- [ ] `hyperframes lint` → 0 errors
+- [ ] `hyperframes validate` → 0 console errors
+- [ ] `npx oxfmt --check` passes
+- [ ] `registry/registry.json` updated with new entry
+- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
+- [ ] `npx hyperframes publish` run (claim your project URL)
+- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
+- [ ] All IDs unique and prefixed
diff --git a/skills/contribute-catalog/templates.md b/skills/contribute-catalog/templates.md
new file mode 100644
index 000000000..84d104ef3
--- /dev/null
+++ b/skills/contribute-catalog/templates.md
@@ -0,0 +1,417 @@
+# Contribute Templates
+
+Copy-paste starter templates for each component type. These embed the proven patterns that pass lint and validate.
+
+## Caption Template
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**Replace checklist:**
+
+- `BLOCKNAME` → your block name (e.g., `cap-swoosh`)
+- `PREFIX` → short unique prefix for IDs (e.g., `sw`)
+- Font family, weight, size → your style's typography
+- Entrance animation → your style's entrance
+- Karaoke highlight → your style's active word treatment
+- Colors → your style's palette
+
+---
+
+## VFX Template
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+**Replace checklist:**
+
+- `COMPNAME` → your component name (e.g., `shimmer-sweep`)
+- Background should be `transparent` so it overlays cleanly
+- No `data-composition-id` or `window.__timelines` — the parent owns timing