docs: consolidate two divergent doc trees; README links stale one

[zeevdr]

Description

The Python SDK ships two divergent doc trees: docs/ (mkdocs, the published site, linked from project URLs) and sdk/docs/ (pdoc-era, plus stale generated sdk/docs/api/*.html). They have drifted (the P0 accuracy bugs live only in sdk/docs/), and both READMEs link to the stale sdk/docs/ tree.

Acceptance criteria

• Pick one canonical tree (mkdocs docs/).
• Migrate still-useful sdk/docs/ content (async guide, error-handling guide) into docs/guide/.
• Remove sdk/docs/ including the stale generated api/*.html (or regenerate it).
• Repoint README.md and sdk/README.md documentation links to the published docs site.

Source: documentation review, 2026-06-07.