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>
* docs(quickstart): collapse prerequisites into expandable accordion
Wraps the Node.js and FFmpeg install instructions in an Accordion
component so the quickstart page is less verbose for returning users
who already have the dependencies installed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs(quickstart): add prerequisite bullet list above accordion
Adds a concise bullet list (Node.js 22+, FFmpeg) above the expandable
install instructions so users can see at a glance what's needed.
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(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>
- 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
* fix(ci): update publish workflow to use bun install
pnpm-lock.yaml was removed in the bun migration but publish.yml
still referenced it. Use bun for install/build, keep pnpm for
publish (publishConfig overrides + --provenance).
* docs: update stale pnpm references to bun across docs and scripts
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
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