docs: Documentation Polish

[pasogott]

User Story: As a user, I want clear documentation, so that I can use the tool effectively.

Tasks

• Review and update README.md
• Add usage examples for all commands
• Create troubleshooting guide
• Add API reference docs
• Create config file examples
• Add FAQ section
• Record demo GIFs/videos (optional)
• Update AGENTS.md with implementation notes

Acceptance Criteria

• README has clear install instructions
• All commands have usage examples
• Troubleshooting section covers common issues
• Config examples are provided
• Documentation is easy to navigate

Files to Update

• README.md
• AGENTS.md
• docs/troubleshooting.md (new)
• docs/api-reference.md (new)
• config.example.yaml

Phase: 5 | User Story: 5.2