docs(decisions): add high/low level api guidance

[mkmeral]

Description

Adds a new decision record documenting our approach to API design: providing both low-level and high-level APIs for new features.

This decision formalizes the pattern we've been following (e.g., in BidiAgent with send/receive vs run) and provides rationale grounded in our tenets. It references the progressive disclosure principle from UX design and the pit of success concept.

This pattern is well-established in SDK design — AWS CDK uses similar "construct levels" (L1/L2/L3) where lower levels map directly to underlying resources while higher levels provide opinionated abstractions.

Related Issues

N/A

Type of Change

• New content
• Content update/revision
• Structure/organization improvement
• Typo/formatting fix
• Bug fix
• Other (please describe):

Checklist

• I have read the CONTRIBUTING document
• My changes follow the project's documentation style
• I have tested the documentation locally using mkdocs serve
• Links in the documentation are valid and working

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[strands-agent]

Documentation Deployment Complete

Your documentation preview has been successfully deployed!

Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-511/