docs: comprehensive README.md with all public API documentation and examples

Co-authored-by: streamich <9773803+streamich@users.noreply.github.com>

Author: Copilot