docs: audit and improve public API surface (AGE-13)

[Larry-Osakwe]

Summary

• Add consistent section organization (=== Section ===) to all public API __init__.py files
• Add module docstrings explaining local definitions vs re-exports
• Document Primary API vs Advanced API patterns
• Group exceptions by category (Configuration, Runtime, Validation)
• Clarify exception distinctions (e.g., MissingContextError vs MissingAccessContextError)

Files Updated

Package	File	Key Changes
keycardai-oauth	__init__.py	Add section comments, mark base exception
keycardai-mcp	client/__init__.py	Add docstring, mark Session types as advanced
keycardai-mcp	server/auth/__init__.py	Add docstring with re-export guide
keycardai-mcp-fastmcp	__init__.py	Add re-export guide, group exceptions by type
keycardai-agents	__init__.py	Reorganize by usage pattern (Client/Server/Delegation)

Acceptance Criteria (AGE-13)

• All __init__.py files reviewed for unintentional exports
• Any debug/experimental APIs identified and either removed or prefixed with _
• Unused exports removed from __all__ lists
• Internal modules properly protected (prefixed with _)
• Document any APIs that should remain but are marked as "advanced use only"
• Verify consistent naming conventions across packages

Test plan

• uv run pytest packages/oauth/tests - 102 passed
• uv run pytest packages/agents/tests - 69 passed, 1 skipped
• uv run pytest packages/mcp-fastmcp/tests - 49 passed
• Verified all documented imports work correctly

Closes AGE-13