[v1.0] Segment and freeze the public API facade

[codeforester]

Goal

Make the stable public surface deliberate and maintainable before 1.0.

Scope

• Classify exported symbols as core, integration, advanced, or provisional.
• Reduce accidental re-exports from base_cli.init.
• Publish a small core API and move optional integrations behind explicit modules/extras.
• Generate an API manifest and compatibility test for every stable symbol.
• Define deprecation and removal timelines for provisional exports.

Acceptance criteria

• The stable API is explicitly listed and reviewed.
• Optional dependencies are not required to import the core API.
• Public-symbol additions require compatibility and documentation coverage.
• The API manifest and generated reference agree.

Project fields

• Status: Backlog
• Priority: P1
• Area: Python
• Initiative: v1.0 Readiness
• Size: L

[codeforester]

2026-09-12 repository review refresh

The public facade currently exports 124 names. Keep the basic adoption path small and classify advanced runtime, protocol, integration, and testing APIs before a v1 freeze. The 1,134-line README also says an adapter may provide async support while App.async_command()/run_async() already ship. CONTRIBUTING.md says framework-wide strict typing is separately tracked, while tests/full_validate.sh already runs strict mypy on the package. Include these entry-document corrections in the API map; do not remove public exports without the documented compatibility process.

Validated against current main (7faf347a5b90969e169c88f3ac18e7202d142dd0). This review files and scopes work; it does not claim implementation or authorize release/admin changes.