docs: improve AI agent discoverability of text, audio, and polish features

[DaKev]

What

Restructures the cutagent capabilities output and README to help AI agents discover and use all available features — especially audio polish (normalize, mix_audio), visual polish (text, animate, fade), and transitions — instead of stopping after basic trim/cut/concat.

Why

AI agents using CutAgent tend to only discover and use trim/cut/concat operations, producing amateur-looking results. They miss text overlays, audio normalization, background music mixing, and transitions because these features are buried in a flat list that agents stop reading early. Professional video editing requires all four phases (analyze, edit, audio polish, visual polish), not just cutting.

How

cutagent capabilities output (cli.py):

• Added overview text at the top explicitly stating all four phases are needed
• Added operation_categories grouping operations into analysis, editing, audio_polish, and visual_polish
• Added quality_checklist with 5 direct questions agents should ask before finishing (e.g., "Audio normalized?", "Titles added?")
• Restructured agent_workflow from a flat 12-step list to a 4-phase structure where audio and visual polish are clearly labeled as essential, not optional
• Added recipes with 3 common patterns (interview cleanup, highlight reel, tutorial polish) that naturally combine text, audio, and transition operations

README.md:

• Added "Text & motion graphics" to the Why CutAgent feature list
• Reorganized CLI Quick Start into the same 4 phases (Analyze, Edit, Audio Polish, Visual Polish)
• Made cutagent capabilities the explicit starting point for AI agents
• Added text and animate to the "Available operations" list in the EDL section

Checklist

• Tests added/updated for new functionality
• All tests pass (pytest) — 264 passed
• JSON output contract maintained (no non-JSON stdout)
• Docstrings added for new public functions
• Type hints on all public function signatures
• CHANGELOG.md updated (for user-facing changes)
• No new runtime dependencies introduced

Made with Cursor