docs: expand API guide for end users

[forhappy]

Summary

• Rework API.md into a task-oriented guide for end users.
• Explain client setup, repository and snapshot concepts, branches and commits, object reads and writes, pagination, atomic multi-object publishing, history, merging, backup, integrity checks, garbage collection, indexes, caching, metrics, errors, retries, and canonical limits.
• Add copy/paste-oriented Rust examples and operational guidance for recovery, resumable work, and external transfer managers.
• Keep the documentation aligned with the current SILO client API and runnable examples.

Validation

• cargo check --locked -p silo-s3-client --examples
• cargo test --locked -p silo-s3-client --lib
• git diff --check

This is opened as a draft for review.