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

[WadydX]

Summary

Updates CLI docs to match current command behavior:

• replaces "non-interactive by default" with command-accurate wording
• clarifies that interactivity is command-specific (init prompts on TTY unless --non-interactive)
• clarifies that --human-friendly is command-specific (not global)
• replaces invalid init --human-friendly example with valid interactive examples

Why

Current docs overstate interactivity behavior and flag scope, which can mislead automation users and create avoidable CLI errors.

Scope

• docs only: docs/packages/cli.mdx

Closes #703

[miguel-heygen]

Review — verified against source code

Issue #703 claims: ✅ Both accurate

Claim 1 — "init is interactive on TTY by default"
Verified in packages/cli/src/commands/init.ts:650:

const interactive = !nonInteractive && process.stdout.isTTY === true;

init defaults to interactive in a terminal. The docs saying "non-interactive by default" is inaccurate for this command.

Claim 2 — "--human-friendly is command-specific, not global"
Verified: --human-friendly is defined only in packages/cli/src/commands/catalog.ts:38. No other command defines it. init.ts has --non-interactive instead (opposite semantic, different flag).

---

PR #705 changes: partially correct but incomplete

The overview section fix (lines 38–64) is accurate. However, the PR misses 4 incorrect --human-friendly references in the init command's own docs section that contradict the fix:

Line	Current text	Problem
159	npx hyperframes init --human-friendly	init has no --human-friendly flag
164	"interactive in --human-friendly"	References non-existent flag
173	| \--human-friendly` | Enable interactive terminal UI |`	Flag table lists a flag that doesn't exist on init
183	"In --human-friendly mode, you choose interactively"	Should reference TTY-default behavior instead

The catalog section references (lines 238, 246, 248) are correct and should stay.

Suggested fix for the missed lines

Line 159 → npx hyperframes init my-video (init is interactive on TTY by default, no flag needed)

Line 164 → "required in non-interactive mode, prompted on TTY"

Line 173 → Remove the --human-friendly row from init's flag table (it doesn't exist in the code)

Line 183 → "In interactive mode (default on TTY), you choose the example interactively. Pass --non-interactive to require --example via flag."

Once these are addressed, the PR accurately reflects the code. The direction is right — just needs to be extended to cover the init command section too.

[miguel-heygen]

The overview section fix is accurate, but the PR needs to also fix the 4 remaining --human-friendly references in the init command docs section that still reference a flag that doesn't exist on init:

1. Line 159: npx hyperframes init --human-friendly → replace with npx hyperframes init my-video (init is interactive on TTY by default)
2. Line 164: "interactive in --human-friendly" → "prompted on TTY by default"
3. Line 173: Remove --human-friendly row from init's flag table — this flag does not exist in packages/cli/src/commands/init.ts
4. Line 183: "In --human-friendly mode, you choose interactively" → "In interactive mode (default on TTY), you choose the example interactively. Pass --non-interactive to require --example via flag."

Without these fixes, the init command docs still advertise a flag that doesn't exist in the code.

[WadydX]

Addressed requested docs fixes in commit e0573c1:

• replaced invalid init --human-friendly example with TTY-default interactive init my-video
• corrected --example description to: required in non-interactive mode, prompted on TTY by default
• removed invalid --human-friendly row from the init flag table
• rewrote init behavior paragraph to reference interactive mode + --non-interactive correctly

Please re-review when convenient.