Improve README.md for users and AI agents

[patrikbraborec]

Summary

README.md is important both for users and agents. It should be comprehensive, well-structured, and serve as a good entry point for both audiences.

Action Items

• Review and improve README.md content and structure
• Ensure README serves as a good reference for AI agents consuming CLI documentation