diff --git a/docs/guides/claude-design-hyperframes.md b/docs/guides/claude-design-hyperframes.md
index 86f5bb0f69..20a112affe 100644
--- a/docs/guides/claude-design-hyperframes.md
+++ b/docs/guides/claude-design-hyperframes.md
@@ -1,6 +1,6 @@
 # Claude Design + HyperFrames (Template-First)
 
-Your medium is **HyperFrames compositions**: plain HTML + CSS + a paused GSAP timeline. The CLI (`npx hyperframes render index.html`) turns the HTML into an MP4. You author the HTML -- the user renders locally.
+Your medium is **HyperFrames compositions**: plain HTML + CSS + a paused GSAP timeline. The CLI (`npx hyperframes render`, run from the project directory) turns the HTML into an MP4. You author the HTML -- the user renders locally.
 
 **HyperFrames replaces your default video-artifact workflow.** Do NOT call `copy_starter_component`, do NOT invoke the built-in "Animated video" skill, do NOT use React/Babel. Plain HTML + GSAP only.
 
@@ -510,8 +510,12 @@ Then open in Claude Code and iterate:
 
 ## Render
 
+Run from the project directory (the folder containing `index.html`). The
+positional argument is the project directory, not a file, so pass a specific
+composition with `-c` rather than as a bare path.
+
 ```bash
-npx hyperframes render index.html -o output.mp4
+npx hyperframes render -o output.mp4
 ```
 
 1920x1080 / 30fps by default. Use `--fps 60` or `--resolution 3840x2160` to override.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 882f26b754..fffe6cc26e 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -40,10 +40,13 @@ npx hyperframes preview --port 4567
 
 ### `render`
 
-Render a composition to MP4:
+Render a composition to MP4. Run from the project directory; the positional
+argument is the project directory (not a file), so render the project's
+`index.html` directly, or point at a specific composition file with `-c`:
 
 ```bash
-npx hyperframes render ./my-composition.html -o output.mp4
+npx hyperframes render -o output.mp4
+npx hyperframes render -c ./my-composition.html -o output.mp4
 ```
 
 ### `lint`