Merge pull request #705 from WadydX/docs/clarify-cli-interactivity-scope

docs(cli): align interactivity and --human-friendly guidance with actual behavior

Author: miguel-heygen

docs/packages/cli.mdx

@@ -35,14 +35,15 @@ npx hyperframes <command>
 
 ## Agent-Friendly by Default
 
-The CLI is **non-interactive by default** — designed so AI agents (Claude Code, Gemini CLI, Codex, Cursor) can drive every command without prompts or interactive UI.
+The CLI is **agent-friendly by default**: commands support explicit flags and parseable output so automation can run reliably.
 
-- All inputs are passed via flags (e.g., `--example`, `--video`, `--output`)
+- Inputs can be passed via flags (for example, `--example`, `--video`, `--output`)
 - Missing required flags fail fast with a clear error and usage example
 - Output is plain text suitable for parsing
-- No interactive prompts, spinners, or selection menus
 
-Add `--human-friendly` to any command to enable the interactive terminal UI with prompts, spinners, and selection menus.
+Interactivity is command-specific. For example, `init` uses prompts on TTY by default; pass `--non-interactive` to force non-interactive mode.
+
+`--human-friendly` is also command-specific (for example, `catalog`). It is not a global flag on every command.
 
 <Tabs>
   <Tab title="Agent mode (default)">
@@ -55,9 +56,11 @@ Add `--human-friendly` to any command to enable the interactive terminal UI with
   </Tab>
   <Tab title="Human mode">
     ```bash
-    # Interactive prompts, spinners, and selection menus
-    npx hyperframes init --human-friendly
-    npx hyperframes upgrade
+    # Command-specific interactive flow
+    npx hyperframes init my-video
+
+    # Interactive picker supported by catalog
+    npx hyperframes catalog --human-friendly
     ```
   </Tab>
 </Tabs>
@@ -155,13 +158,13 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     # Include Tailwind CSS browser-runtime support
     npx hyperframes init my-video --example blank --tailwind
 
-    # Human mode — interactive prompts
-    npx hyperframes init --human-friendly
+    # Human mode — interactive prompts on TTY by default
+    npx hyperframes init my-video
     ```
 
     | Flag | Description |
     |------|-------------|
-    | `--example, -e` | Example to scaffold (required in default mode, interactive in `--human-friendly`) |
+    | `--example, -e` | Example to scaffold (required in non-interactive mode, prompted on TTY by default) |
     | `--resolution` | Canvas preset: `landscape` (1920×1080), `portrait` (1080×1920), `landscape-4k` (3840×2160), `portrait-4k` (2160×3840). Aliases: `1080p`, `4k`, `uhd`. Default: keep template dimensions. |
     | `--video, -V` | Path to a video file (MP4, WebM, MOV) |
     | `--audio, -a` | Path to an audio file (MP3, WAV, M4A) |
@@ -170,7 +173,6 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `--skip-transcribe` | Skip automatic whisper transcription |
     | `--model` | Whisper model for transcription (e.g. `small.en`, `medium.en`, `large-v3`) |
     | `--language` | Language code for transcription (e.g. `en`, `es`, `ja`). Filters non-target speech. |
-    | `--human-friendly` | Enable interactive terminal UI with prompts |
 
     | Example | Description |
     |----------|-------------|
@@ -180,7 +182,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
     | `swiss-grid` | Structured grid layout |
     | `vignelli` | Bold typography with red accents |
 
-    In default (agent) mode, `--example` is required — the CLI errors with a usage example if missing. In `--human-friendly` mode, you choose interactively. When `--video` or `--audio` is provided, the CLI automatically transcribes the audio with Whisper and patches captions into the composition (use `--skip-transcribe` to disable).
+    In non-interactive mode, `--example` is required — the CLI errors with a usage example if missing. In interactive mode (default on TTY), you choose the example interactively. Pass `--non-interactive` to require `--example` via flag. When `--video` or `--audio` is provided, the CLI automatically transcribes the audio with Whisper and patches captions into the composition (use `--skip-transcribe` to disable).
 
     `--tailwind` injects the pinned Tailwind v4 browser runtime into scaffolded HTML and exposes a `window.__tailwindReady` promise that renders wait on before capturing frame 0. Use the `/tailwind` skill when editing these projects so agents follow v4 CSS-first patterns instead of v3 `tailwind.config.js` and `@tailwind` directive patterns. The browser runtime is still intended for scaffolded projects and quick iteration; for fully offline or locked-down production renders, compile Tailwind to CSS and include the stylesheet directly.