[AAASM-3530] 📝 (docs): Declare framework compatibility + reconcile pydantic-ai range

[Chisanan232]

What

Declares the Python SDK's supported AI-agent frameworks with version ranges + tested versions, and reconciles a pydantic-ai pin contradiction.

• New canonical matrix docs/compatibility/frameworks.md — the 7 supported frameworks (langchain, langgraph, pydantic_ai, crewai, google_adk, mcp, openai_agents) with each adapter's supported range and the AAASM-3525 tested version (crewai 1.14.x, openai-agents 0.17.x, mcp 1.27.x, pydantic-ai >=0.3.0, etc.). Links to the core cross-component matrix, documents why frameworks are user-pinned (not optional extras), and states the adapter/test sync policy. Wired into the compatibility nav + index.
• README — adds a "Framework compatibility" section with the same table and the core-matrix link.
• Reconciles the pydantic-ai contradiction — docs/examples/pydantic-ai.md pinned pydantic-ai>=0.1.0,<0.3.0 and claimed hooks only attach on 0.1.x–0.2.x, but the adapter now auto-detects the hook point across versions (Tool._run on <0.3.0, AbstractToolset.call_tool on >=0.3.0) and >=0.3.0 is the line the dev/test group pins and CI exercises. The example now tracks >=0.3.0, matching pyproject.toml.

Why

Per AAASM-3525 the supported-framework surface is tested but the docs didn't declare it for users or pin version ranges. The pydantic-ai example also contradicted the tested >=0.3.0 pin in pyproject.toml.

How to verify

• uv run --group docs mkdocs build --strict — passes (no broken links; the release/RUNBOOK.md not-in-nav INFO is pre-existing).
• uv sync still resolves (no manifest change).
• Cross-check the published ranges against agent_assembly/adapters/*/adapter.py get_supported_versions() and the pyproject.toml test group.

The core-matrix link is a /stable/ URL that 404s until GA, by design (consistent with AAASM-3523).

Note: docs-only PR — ci.yaml excludes docs/**/*.md, so no CI runs here (review-required, not a failure).

Refs AAASM-3530

🤖 Generated with Claude Code

[Chisanan232]

🤖 Claude Code — PR review (record)

CI: ✅ all green.

Scope vs AAASM-3530 (python part): ✅ covers it. Adds a canonical "Framework compatibility" matrix (docs/compatibility/frameworks.md + mkdocs nav + README section) for the 7 Python frameworks with supported range / tested version, sourced from each adapter's get_supported_versions() + the AAASM-3525 tested versions (crewai 1.14.x, openai-agents 0.17.x, mcp 1.27.x). Links the canonical core matrix via the /stable/ URL (404-until-GA, consistent with AAASM-3523). Reconciled the pydantic-ai contradiction — the example's stale <0.3.0 pin → >=0.3.0 in all 4 spots, explaining the adapter's dual hook-point detection. mkdocs build --strict passes.

Verdict: ✅ Ready to approve & merge (AAASM-3530 set). Refs AAASM-3530.