* docs: add prompt cookbook + prompting guide for AI agents
Addresses user feedback that there's no guidance on how to actually
prompt Claude Code (or other agents) once the hyperframes skills are
installed. Adds copy-pasteable example prompts in the README and
quickstart, a new prompting guide page, and a starter-prompt nudge in
the `hyperframes init` output.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(prompting): add vocabulary tables, rules, and TTS voice guide
Merges the best content from the internal prompt guide into
prompting.mdx: easing vocabulary, caption tone table, transition
energy matrix, audio-reactive frequency mapping, marker highlight
modes, TTS voice recommendations, rendering quality presets, and
framework rules (technical requirements vs best practices).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(prompting): rename page title to "Prompt Guide"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: remove greensock/gsap-skills dependency, fix Math.random nuance
The bundled skills/gsap/ already covers the GSAP surface needed for
HyperFrames compositions. Installing greensock/gsap-skills on top adds
a competing full-ecosystem skill that's mostly irrelevant (ScrollTrigger,
Draggable, SplitText, etc.) and can confuse agents about which GSAP
context to load.
Also adds seeded-PRNG nuance to the Math.random() rule in the prompt
guide (matching the skill's actual guidance).
Removed from: skills.ts, README, AGENTS.md, shared AGENTS.md/CLAUDE.md,
and prompting.mdx.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: require minimal reproduction link in bug report template
Adds a required "Link to reproduction" input field asking users to push
a minimal repro to a public GitHub repo (scaffolded via
`hyperframes init repro --non-interactive --example blank`).
Also consolidates the OS/Node/FFmpeg/version fields into a single
"Environment" field using `npx hyperframes info` output — fewer fields
to fill, more consistent data.
Follows the same pattern as Next.js and Gatsby issue templates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(issue-template): use hyperframes doctor for environment info
`hyperframes info` only prints project metadata (resolution, duration,
elements). `hyperframes doctor` prints the full environment: version,
Node.js, FFmpeg, Chrome, memory, disk, Docker — everything needed to
diagnose bugs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(prompting): mention validate alongside lint in anti-patterns
Per Vance's review comment — validate catches runtime errors (JS
exceptions, missing assets, contrast) that lint doesn't.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: replace libretto example URL with hyperframes repo
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## What
Fixes the README skills table to match actual skill names, and moves two orphaned script directories into the `hyperframes` skill where they belong.
## Why
**README**: Listed `hyperframes-compose` and `hyperframes-captions` as separate skills — these don't exist. Captions/compose are part of the `hyperframes` skill. Also listed `gsap-core, gsap-timeline, gsap-plugins, ...` but the actual skill is just `gsap`. Missing `hyperframes-cli` entirely.
**Orphaned scripts**: `skills/hyperframes-animation-map/` and `skills/hyperframes-contrast/` had scripts but no `SKILL.md` — they looked like broken skills and wouldn't be installed by `npx skills add`. They're helper scripts invoked by the main `hyperframes` skill (SKILL.md already references them in the "Quality Checks" section). Moving them under `skills/hyperframes/scripts/` makes them part of the skill they belong to.
## How
**README skills table** — corrected to match the 4 actual skills:
- `hyperframes` (was `hyperframes-compose` + `hyperframes-captions`)
- `hyperframes-cli` (was missing)
- `hyperframes-registry` (unchanged)
- `gsap` (was `gsap-core, gsap-timeline, gsap-plugins, ...`)
**Script moves:**
- `skills/hyperframes-animation-map/scripts/animation-map.mjs` → `skills/hyperframes/scripts/`
- `skills/hyperframes-contrast/scripts/contrast-report.mjs` → `skills/hyperframes/scripts/`
- Removed empty `skills/hyperframes-animation-map/` and `skills/hyperframes-contrast/`
- Updated path references in SKILL.md, both script headers, and `contrast-audit.browser.js`
## Test plan
- [ ] `grep -r "hyperframes-animation-map\|hyperframes-contrast" --include="*.md" --include="*.mjs" --include="*.js" --include="*.ts" .` returns no results
- [ ] `ls skills/` shows only `gsap`, `hyperframes`, `hyperframes-cli`, `hyperframes-registry`
- [ ] README skills table matches `skills/*/SKILL.md` names
- [x] Documentation updated (if applicable)
## What
Restructures the README to lead with skills-first onboarding, adds a demo GIF, surfaces the catalog, fixes incorrect pnpm references in contributing docs, and corrects the HTML example to use actual attribute names.
## Why
The README told a CLI-first story while the homepage (hyperframes.heygen.com) tells an AI-agent-first story. For a project that brands itself "built for agents," the GitHub landing page should match. Additionally, 50+ catalog blocks were invisible from GitHub, the player and shader-transitions packages were missing from the packages table, and the contributing docs referenced pnpm while the repo uses bun.
## How
**README changes:**
- Quick Start restructured: skills install as Option 1 (recommended), manual CLI as Option 2
- Added demo GIF rendered with HyperFrames itself (HTML + GSAP composition → MP4 → GIF)
- Added Catalog section with install examples and link
- Added `@hyperframes/player` and `@hyperframes/shader-transitions` to packages table
- Added npm downloads badge
- Fixed HTML example: `data-track` → `data-track-index`, added missing `class="clip"` on img
- Condensed Skills section into a concise table
- Documentation link now points to `/introduction` (Mintlify docs) instead of the landing page
**testing-local-changes.mdx:**
- All `pnpm` references replaced with `bun` (14 occurrences)
- Path references updated from `hyperframes-oss` to `hyperframes`
## Test plan
- [ ] Verify README renders correctly on GitHub (logo, badges, GIF, tables, code blocks)
- [ ] Verify GIF loops and is readable at GitHub's default README width
- [ ] Verify all links resolve (docs site, catalog, packages, contributing)
- [ ] Read through testing-local-changes.mdx for any remaining pnpm references
- [x] Documentation updated (if applicable)
Replace old text-only wordmarks and complex favicon with new HyperFrames
brand assets featuring the gradient icon. Add dark/light logo switching
to README via GitHub's <picture> element.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## What
New skill `hyperframes-registry` that teaches AI coding agents how to install and wire registry blocks and components into HyperFrames compositions.
### Skill structure
```
skills/hyperframes-registry/
SKILL.md — triggers, overview, quick reference
references/
install-locations.md — default paths, hyperframes.json config
wiring-blocks.md — iframe inclusion, data attributes, positioning
wiring-components.md — snippet merging (HTML, CSS, JS, timeline)
discovery.md — manifest reading, item fields, available items table
demo-html-pattern.md — why components ship demo.html, structure conventions
examples/
add-block.md — worked example: data-chart block install + wiring
add-component.md — worked example: shimmer-sweep component install + wiring
```
## Why
Phase B of the catalog plan (PR 10). Without this skill, agents using `hyperframes add` have to guess how to wire installed items into compositions. The skill encodes the iframe/snippet patterns so agents get it right on the first attempt.
## How
- SKILL.md frontmatter triggers on: `hyperframes add`, "block", "component", `hyperframes.json`
- References cover every step: discovery, install, wiring blocks (iframe), wiring components (snippet merge), and the demo.html convention
- Two worked examples walk through complete install-to-preview workflows
- Updated CLAUDE.md skills table + trigger rules, README.md skills table, docs/packages/cli.mdx
## Test plan
- [x] `scripts/lint-skills.ts` passes (checked 4 skill files, no issues)
- [x] `oxfmt --check` passes on all markdown files
- [x] SKILL.md frontmatter has valid `name` and `description`
- [x] All reference links in SKILL.md resolve to existing files
- [x] CLAUDE.md, README.md, and docs CLI page updated with new skill
* feat(skills): add hyperframes-cli skill for CLI workflow guidance
Adds a new skill that teaches AI agents how to use the HyperFrames CLI
(init, lint, dev, render, doctor). Previously, agents had no way to
discover the CLI — the compose-video skill only covered HTML authoring.
This led to agents searching for binaries, finding the monorepo, and
running bun run studio manually instead of using npx hyperframes dev.
Also registers the skill in init.ts so new projects get it bundled
alongside hyperframes-compose and hyperframes-captions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(cli): rename dev command to preview
The command starts a preview server — "preview" describes what users
are doing more accurately than "dev". Updates the command name, file
name, all CLI references, docs, skills, and template CLAUDE.md.
22 files updated across CLI source, docs, skills, and templates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(skills): replace stale dev reference with preview in CLI skill
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(docs): catch remaining dev references missed in rename
- testing-local-changes.mdx: two inline command examples
- troubleshooting.mdx: anchor link #dev → #preview, "dev server" → "preview server"
- cli.mdx: "dev server" → "preview server"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add npm version and MIT license badges (matching React/Remotion/Next.js conventions)
- Remove non-standard Docs badge
- Move Documentation section from bottom of README to right after Quick Start
for better discoverability (follows patterns from React, Remotion, Vite)
- Link to quickstart at hyperframes.heygen.com/quickstart
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Namespace skill names with `hyperframes-` prefix for clearer identity in
OSS contexts where users may have other skills installed.
Updates skill directories, SKILL.md frontmatter, CLAUDE.md, README.md,
CLI build script, init command, and project template.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- README quick start now leads with opening in an AI agent after init
- Quickstart docs updated: interactive wizard is default, --non-interactive
replaces --human-friendly, edit step mentions AI agent workflow
New HyperFrames projects created via `hyperframes init` now include:
- CLAUDE.md + AGENTS.md — teaches AI agents about skills, commands,
project structure, and framework rules (class="clip", timeline
registration, determinism). Agents know to invoke /compose-video
before writing compositions.
- .claude/skills/{compose-video,captions} — project-level skills for
immediate availability in the current agent session (global skills
require a session restart to discover).
- Updated next-steps output with `hyperframes docs <topic>` and a
link to hyperframes.heygen.com.
- Updated README with "AI Agent Skills" section documenting
`npx hyperframes skills` and `npx skills add` install paths.
- Repo-level CLAUDE.md for framework contributors.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add READMEs for all 5 packages (core, engine, producer, cli, studio)
with install, overview, basic usage, and links to full docs
- Rewrite core README from internal doc to OSS-facing format
- Polish root README: add badges, packages table, docs link, requirements
- Add AI usage policy and BDFL governance statement to CONTRIBUTING.md
- Genericize license references (pending final license decision)
- Docs URL set to hyperframes.heygen.com
Addresses VA-850.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- .gitignore: remove blanket video file ignores (may need LFS for regression test fixtures)
- CONTRIBUTING.md: strip dev setup details until packages are ported (leave TODO)
- README.md: strip packages table, comparison, requirements, docs link (leave TODO)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- README with hero section, quick start, HTML schema example, package overview, and Remotion comparison
- MIT LICENSE (copyright HeyGen)
- CONTRIBUTING.md with dev setup, commit conventions, and project structure
- GitHub issue templates (bug report, feature request) and PR template
- .gitignore for Node.js/TypeScript projects
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
