PR 4/17 of the catalog system rollout. Single clean cut — the old flag
is gone, replaced by --example. Alias changes from -t to -e.
BREAKING CHANGE: --template is no longer accepted. Use --example <name>
instead. When the old flag is used, the CLI exits 1 with a rename hint
that includes the corrected command line.
## What
- Rename the init command's --template flag to --example (alias -e)
- Accept --template as a recognized-but-errored flag so users get a
clear diagnostic instead of citty silently ignoring it and producing
a blank project
- Update all user-visible strings that referenced "template" as a
user-facing concept in the init flow:
- picker prompt: "Pick a template" → "Pick an example"
- step comment: "Pick template" → "Pick example"
- offline-fallback suggestion: "Use --template blank" → "Use --example blank"
- New init.test.ts covering: --example scaffolds, --template exits 1
with the rename message
## Docs (bundled in this PR per the tracker principle)
- docs/templates.mdx — all --template references
- docs/quickstart.mdx — agent-mode + video-mode examples
- docs/packages/cli.mdx — --help table, prose, alias (-e)
- packages/cli/src/docs/templates.md — help-topic doc
- No updates needed in README.md or CONTRIBUTING.md (they don't
reference the flag)
The user-facing renames of the templates.mdx page, nav entry, and
directory routes are deferred to PR 11 (catalog discoverability UX)
as planned.
## Why
Two motivations: (1) "examples" matches shadcn + Remotion convention
for full-project scaffolds and frees "template" for future
parameterization work (string templating, placeholder substitution);
(2) once hyperframes add lands in PR 5, "template" vs "block" vs
"component" would be three subtly different concepts — renaming the
old one to "example" makes the taxonomy self-explaining.
## How
- citty silently ignores unknown flags. That meant naively removing
--template would cause hyperframes init my-video --template warm-grain
to silently fall through and scaffold a blank project. Very
confusing. So --template stays declared but its run handler
immediately errors with a rename hint including the corrected
command. This is user guidance, not backwards compat — the old
flag has no working behavior.
- Internal names (templateId local, getStaticTemplateDir function,
BUNDLED_TEMPLATES constant) are unchanged in this PR. They're
implementation details; their rename is scheduled for PR 5 when
the compat shims in packages/cli/src/templates/ are fully removed.
## Test plan
- [x] bun run test in packages/cli: 72 passed (was 70 on #254, +2
new init.test.ts cases). Same 4 pre-existing failures unchanged
- [x] Manual smoke: init /tmp/x --example blank succeeds; init /tmp/y
--template blank errors with rename hint and exits 1
- [x] bunx oxfmt + bunx oxlint on changed files: clean
- [x] Pre-commit typecheck (core + studio): clean
- Also fixes an incidental regression from the PR 3 simplify-fix
commit: the resolver test for loadAllItems' warning path was still
spying on console.warn after the onWarn callback refactor. Now
uses the callback directly.
## Stacks on
#254 (PR 3 — registry resolver + installer).
## Next in stack
PR 5 — feat(cli): add command + hyperframes.json. The big UX PR
where init.ts gets fully ported to the new resolver, the compat
shims are removed, and users gain the add verb for installing
blocks and components into existing projects.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The tts command was implemented (PR #201) but never added to the root-level
help display or documentation. This adds it to:
- help.ts GROUPS (AI & Integrations) so it appears in `hyperframes --help`
- docs/packages/cli.mdx with usage examples and flag reference
- CLAUDE.md "Adding CLI Commands" checklist: new steps 4-5 require adding
commands to help.ts groups and docs, preventing future omissions
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(docs): add template gallery page with visual previews
* fix(docs): remove invalid MDX heading anchors
* chore: retrigger CI
* feat(docs): merge gallery into templates page with hover-to-play video previews
- Consolidated gallery.mdx and templates.mdx into single templates.mdx
- Moved templates page to Getting Started section
- Added MP4 video previews rendered by hyperframes (hover to play)
- Custom JS for hover-to-play behavior (Mintlify strips JSX event handlers)
- 2-column grid for landscape, 3-column for portrait
- Remotion-style cards with gradient overlay labels
* fix(docs): update broken links after templates page move
* ci(regression): remove scripts/ from regression trigger paths
scripts/ contains dev utilities (lint, versioning, preview generation)
that don't affect the rendering engine.
* 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>
* feat(cli,core): add standalone transcribe command, transcript normalization, and caption lint rules
- Add `hyperframes transcribe` command for transcribing audio/video and importing
existing transcripts (SRT, VTT, OpenAI Whisper API JSON, whisper.cpp JSON)
- Add transcript format normalizer (normalize.ts) with auto-detection and
conversion to standard [{text, start, end}] word arrays
- Upgrade default whisper model from base.en to small.en for better accuracy
- Add --model and --language flags to both `transcribe` and `init` commands
- Extract shared patchCaptionHtml() to eliminate duplication between init.ts
and transcribe.ts (init.ts reduced by ~55 lines)
- Add 3 caption lint rules: caption_exit_missing_hard_kill,
caption_text_overflow_risk, caption_container_relative_position
- Update captions skill with model guide, format docs, music guidance,
text overflow prevention, caption exit guarantee pattern
- Expand captions skill trigger to cover lyrics, karaoke, lyric videos
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(cli): add transcribe command and --model/--language flags to CLI docs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cli): fix blank template lint issues
- blank/index.html: remove data-start from video (was nested in timed parent),
add class="clip" for initial hidden state
- blank/captions.html: add max-width + overflow:hidden to prevent text clipping,
add tl.set hard kill after exit tween to prevent stuck captions
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add lint-after-edit rule to repo and project CLAUDE.md
Agents must run `npx hyperframes lint` after editing compositions.
Also expand captions skill description in project template.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* style: format _shared/CLAUDE.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Respect `--json` flag on all lint exit paths so agents always get machine-readable output
- Separate `infoCount` from `warningCount` in linter results (was conflated)
- Display `info` vs `warning` severity distinctly in lint output
Document the --format webm flag, VP9 alpha output, overlay workflow
with FFmpeg, and transparent background requirement for compositions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Document the three dev server modes (embedded/local studio/monorepo)
- Add --port flag to dev command
- Document _meta envelope on all --json commands
- Document upgrade --check --json for agent consumption
- Document passive update notices and HYPERFRAMES_NO_UPDATE_CHECK
- Update doctor output example with Version check row
- Fix README default port from 3000 to 3002
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Major improvements across all 18 pages:
- Use Mintlify components: <Steps> for tutorials, <Tabs> for alternatives,
<CodeGroup> for multi-platform commands, <Tree> for directory structures,
<AccordionGroup> for FAQ/scannable content, <Mermaid> for diagrams
- Add filename annotations to all code blocks (e.g., ```html index.html)
- Add numbered comments inside multi-step code examples
- Show expected terminal output after CLI commands
- Add "When to use" / "When NOT to use" sections to all package pages
- Add "Next Steps" CardGroup to every page (no dead-end pages)
- Cross-link between pages at point of curiosity (not just "see also" dumps)
- Expand thin pages (engine, studio) with architecture details and examples
- Add decision guides (rendering modes, template selection)
- Use <Warning> and <Note> sparingly (max 2-3 per page)
Also adds DOCS_GUIDELINES.md at repo root with writing standards.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
James