[Agentic DX] gp-libs: low-to-high lift plugin/API clarity roadmap

[tony]

Context

Review focused on flat src/*.py modules, plugin entry points, and docs coverage.

Goal

Improve extension discoverability and API boundaries for mixed pytest/sphinx utilities.

Low-lift ideas

• Document which modules are stable API vs incubating internals.
• Add py.typed (if type hints are intended for downstream use).
• Add a concise capability table for each extension/plugin entry point.

Medium-lift ideas

• Consider a namespaced package layout (src/gp_libs/...) instead of flat modules.
• Separate CLI concerns from reusable parser/transform components.
• Add contract tests for plugin registration and advertised APIs.

High-lift ideas

• Publish a machine-readable plugin manifest (capabilities, options, output contracts).
• Auto-generate extension docs from that manifest.

Done when

• API boundaries are explicit.
• Plugins are discoverable by docs and tooling.
• Module structure supports safer long-term evolution.