enhancement: classify and freeze the public API surface (#242)

.github/workflows/docs.yml

@@ -17,6 +17,7 @@ on:
       - ".github/workflows/dependency-matrix.yml"
       - ".github/workflows/compatibility.yml"
       - "scripts/generate_api_reference.py"
+      - "scripts/generate_core_surface.py"
       - "scripts/generate_compatibility_dashboard.py"
       - ".github/workflows/tests.yml"
       - ".github/workflows/dependency-matrix.yml"
@@ -74,6 +75,8 @@ jobs:
 
       - name: Validate generated public API reference
         run: python scripts/generate_api_reference.py --check
+      - name: Validate generated core surface
+        run: python scripts/generate_core_surface.py --check
 
       - name: Build documentation with strict warnings
         run: python -m mkdocs build --strict --site-dir site

CHANGELOG.md

@@ -14,6 +14,8 @@ and versions are tracked in the repo-root `VERSION` file.
 ### Changed
 
 - Include `uv.lock` freshness in the authoritative local validation aggregate (#424).
+- Classify the compatibility facade in a reviewed API manifest and add the
+  smaller `base_cli.core` starting surface for new applications (#242).
 
 ## [0.5.1] - 2026-10-10
 

README.md

@@ -88,6 +88,11 @@ and independently released.
 an application's project model. Base is one consumer of the library, not part
 of its generic contract.
 
+New applications can start with the smaller `base_cli.core` surface. The
+compatibility facade remains available for existing 0.x consumers; the
+[API manifest](https://basefoundry.github.io/base-cli/api-stability/#public-surface)
+classifies advanced and optional integration APIs.
+
 It is intentionally thin. Click still owns argument parsing and command
 execution, while `base_cli` provides reusable lifecycle behavior:
 

docs/api-manifest.json

@@ -0,0 +1,138 @@
+{
+  "schema_version": 1,
+  "facade": "base_cli",
+  "tiers": {
+    "core": [
+      "App",
+      "ApplicationStateT",
+      "BaseCliDeprecationWarning",
+      "ConfigT",
+      "ConfigurationError",
+      "Context",
+      "ExitCode",
+      "LIFECYCLE_META_KEY",
+      "LifecycleOption",
+      "LifecycleOptions",
+      "LifecycleValues",
+      "ServicesT",
+      "__version__",
+      "argument",
+      "attach",
+      "command",
+      "configure_logger",
+      "deprecated",
+      "get_current_context",
+      "get_lifecycle_values",
+      "log_critical",
+      "log_debug",
+      "log_error",
+      "log_info",
+      "log_warning",
+      "option",
+      "run_app",
+      "testing"
+    ],
+    "integration": [
+      "TelemetryOptions",
+      "TelemetrySession",
+      "TyperAdapter",
+      "asyncio_adapter",
+      "attach_typer",
+      "get_typer_command",
+      "integrations",
+      "run_async",
+      "try_render_rich_table"
+    ],
+    "advanced": [
+      "AttachmentAdapter",
+      "AttachmentContextFactory",
+      "AttachmentContract",
+      "AttachmentServiceFactory",
+      "BOOLEAN",
+      "BatteriesIncludedConfigLoader",
+      "COMMAND_ENTRY_POINT_GROUP",
+      "CliProfile",
+      "CommandCodec",
+      "CommandExtension",
+      "CommandFilterNormalizer",
+      "CommandProtocolError",
+      "CommandSchemaRegistry",
+      "ConfigLoader",
+      "ConfigSnapshot",
+      "DEFAULT_SCHEMA_REGISTRY",
+      "DisplayCommandResolver",
+      "ENTRY_POINT_GROUPS",
+      "EXTENSION_API_VERSION",
+      "EnvironmentConfigLoader",
+      "ExtensionCollisionError",
+      "ExtensionCompatibilityError",
+      "ExtensionDescriptor",
+      "ExtensionDiscovery",
+      "ExtensionDiscoveryError",
+      "ExtensionLoadError",
+      "ExtensionLoadResult",
+      "ExtensionsDisabledError",
+      "FieldSpec",
+      "FrameworkConfig",
+      "HistoryDisplayResolver",
+      "HistoryWriter",
+      "JSON_CONTRACT_VERSION",
+      "JSON_ERROR_SCHEMA",
+      "JSON_LOG_SCHEMA",
+      "JSON_OUTPUT_SCHEMA",
+      "JsonLogFormatter",
+      "MAX_JSON_LOG_MESSAGE_LENGTH",
+      "NDJSON_SCHEMA",
+      "NDJSON_SCHEMA_VERSION",
+      "NULLABLE_STRING",
+      "NdjsonWriter",
+      "OutputFormatError",
+      "PLUGIN_ENTRY_POINT_GROUP",
+      "PROFILE_ENTRY_POINT_GROUP",
+      "PUBLIC_OUTPUT_FORMATS",
+      "PluginExtension",
+      "ProfileExtension",
+      "ProjectDiscovery",
+      "ProjectInfo",
+      "RECORD_SCHEMAS",
+      "RetentionPolicy",
+      "RuntimeBinding",
+      "RuntimeLayout",
+      "RuntimeResolver",
+      "STRING",
+      "StructuredRecord",
+      "StructuredResultWriter",
+      "UserConfigLoader",
+      "WorkspaceRootResolver",
+      "command_filters",
+      "command_matches",
+      "command_protocol",
+      "delegated_display_command",
+      "deprecations",
+      "dumps_envelope",
+      "dumps_record",
+      "dumps_records",
+      "error_envelope",
+      "extensions",
+      "get_command_app",
+      "history",
+      "is_terminal",
+      "json_contracts",
+      "loads_records",
+      "normalize_command_filter",
+      "normalize_command_filters",
+      "output_format_choices",
+      "redact_json_value",
+      "register_record_schema",
+      "render_document",
+      "render_records",
+      "resolve_output_format",
+      "success_envelope"
+    ],
+    "provisional": [
+      "experimental",
+      "inspection_envelope",
+      "render_inspection_json"
+    ]
+  }
+}