base-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{base_cli-0.4.2 → base_cli-0.4.3}/.github/workflows/compatibility.yml

@@ -20,7 +20,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
-        typer-version: ["0.25.1", "0.26.0", "0.27.1"]
+        typer-version: ["0.25.1", "0.26.0", "0.27.1", "0.27.2"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Set up Python
@@ -66,3 +66,12 @@ jobs:
           for tests in compatibility/consumers/*/tests; do
             python -m pytest "$tests"
           done
+      - name: Record dated compatibility evidence
+        run: python scripts/record_compatibility_evidence.py > compatibility-evidence.json
+      - name: Upload compatibility evidence
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: base-cli-compatibility-evidence-${{ github.run_id }}
+          path: compatibility-evidence.json
+          if-no-files-found: error
+          retention-days: 90

base_cli-0.4.3/.github/workflows/dependency-matrix.yml

@@ -0,0 +1,48 @@
+name: Dependency compatibility
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  core:
+    name: Click ${{ matrix.click-version }} / PyYAML ${{ matrix.pyyaml-version }} / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.14"]
+        click-version: ["8.1.*", "8.2.*", "8.3.*", "8.4.*"]
+        pyyaml-version: ["6.0.*"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install framework and test dependencies
+        run: python -m pip install "setuptools<77" "wheel" ".[dev]"
+      - name: Select tested core dependency lines
+        run: |
+          python -m pip install --upgrade --force-reinstall \
+            "click==${{ matrix.click-version }}" \
+            "PyYAML==${{ matrix.pyyaml-version }}"
+      - name: Verify resolved dependency contract
+        run: |
+          python - <<'PY'
+          from importlib.metadata import version
+
+          click_version = version("click")
+          yaml_version = version("PyYAML")
+          print(f"Click {click_version}; PyYAML {yaml_version}")
+          PY
+      - name: Run core suite
+        run: python -m pytest

{base_cli-0.4.2 → base_cli-0.4.3}/.github/workflows/docs.yml

@@ -11,6 +11,16 @@ on:
       - "mkdocs.yml"
       - "pyproject.toml"
       - "scripts/validate_docs.py"
+      - "scripts/validate_changelog.py"
+      - "scripts/generate_compatibility_dashboard.py"
+      - ".github/workflows/tests.yml"
+      - ".github/workflows/dependency-matrix.yml"
+      - ".github/workflows/compatibility.yml"
+      - "scripts/generate_api_reference.py"
+      - "scripts/generate_compatibility_dashboard.py"
+      - ".github/workflows/tests.yml"
+      - ".github/workflows/dependency-matrix.yml"
+      - ".github/workflows/compatibility.yml"
       - "tests/validate.sh"
       - ".github/workflows/docs.yml"
   pull_request:
@@ -21,6 +31,7 @@ on:
       - "mkdocs.yml"
       - "pyproject.toml"
       - "scripts/validate_docs.py"
+      - "scripts/generate_api_reference.py"
       - "tests/validate.sh"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
@@ -50,7 +61,13 @@ jobs:
         run: python -m pip install ".[docs]"
 
       - name: Validate repository links and examples
-        run: python scripts/validate_docs.py
+        run: |
+          python scripts/validate_docs.py
+          python scripts/validate_changelog.py
+          python scripts/generate_compatibility_dashboard.py --check
+
+      - name: Validate generated public API reference
+        run: python scripts/generate_api_reference.py --check
 
       - name: Build documentation with strict warnings
         run: python -m mkdocs build --strict --site-dir site

{base_cli-0.4.2 → base_cli-0.4.3}/.github/workflows/package.yml

@@ -12,6 +12,11 @@ on:
       - "scripts/validate_package_artifact.py"
       - "scripts/validate_installed_package.py"
       - "scripts/validate_examples.py"
+      - "scripts/generate_release_metadata.py"
+      - "scripts/validate_release_metadata.py"
+      - "scripts/validate_changelog.py"
+      - "scripts/validate_release_ref.py"
+      - "CHANGELOG.md"
       - "examples/**"
       - "compatibility/**"
       - "docs/releasing.md"
@@ -78,6 +83,15 @@ jobs:
       - name: Validate repository baseline
         run: ./tests/validate.sh
 
+      - name: Validate changelog
+        run: python scripts/validate_changelog.py
+
+      - name: Validate tagged release notes
+        if: ${{ github.ref_type == 'tag' }}
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python scripts/validate_release_ref.py
+
       - name: Prepare clean artifact destination
         run: |
           git clean -ffdx
@@ -95,14 +109,37 @@ jobs:
       - name: Validate package indexes
         run: python -m twine check dist/*
 
+      - name: Generate release checksums and SPDX SBOM
+        env:
+          SOURCE_REVISION: ${{ github.sha }}
+          SOURCE_DATE_EPOCH: ${{ github.event.head_commit.timestamp || '0' }}
+        run: python scripts/generate_release_metadata.py dist
+
+      - name: Validate release checksums and SPDX SBOM
+        env:
+          SOURCE_REVISION: ${{ github.sha }}
+        run: python scripts/validate_release_metadata.py dist
+
       - name: Upload reviewed distributions
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: base-cli-dist-${{ github.run_id }}
-          path: dist/*
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
           if-no-files-found: error
           retention-days: 14
 
+      - name: Upload release metadata
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: base-cli-release-metadata-${{ github.run_id }}
+          path: |
+            dist/SBOM.spdx.json
+            dist/SHA256SUMS
+          if-no-files-found: error
+          retention-days: 90
+
   smoke:
     name: Install smoke test (Python ${{ matrix.python-version }})
     needs: build
@@ -184,3 +221,74 @@ jobs:
         uses: pypa/gh-action-pypi-publish@4bb033805d9e19112d8c697528791ff53f6c2f74
         with:
           packages-dir: dist
+
+  attest:
+    name: Attest reviewed release
+    needs: [build, smoke]
+    if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - name: Download reviewed distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: base-cli-dist-${{ github.run_id }}
+          path: dist
+
+      - name: Download release metadata
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: base-cli-release-metadata-${{ github.run_id }}
+          path: dist
+
+      - name: Attest artifact provenance
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
+        with:
+          subject-checksums: dist/SHA256SUMS
+
+      - name: Attest SPDX SBOM
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
+        with:
+          subject-checksums: dist/SHA256SUMS
+          sbom-path: dist/SBOM.spdx.json
+
+  release:
+    name: Create GitHub Release
+    needs: [build, smoke, publish, attest]
+    if: ${{ github.event_name == 'push' && github.ref_type == 'tag' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Download reviewed distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: base-cli-dist-${{ github.run_id }}
+          path: dist
+
+      - name: Download release metadata
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: base-cli-release-metadata-${{ github.run_id }}
+          path: dist
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag="$GITHUB_REF_NAME"
+          assets=(dist/*.whl dist/*.tar.gz dist/SHA256SUMS dist/SBOM.spdx.json)
+          if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release upload "$tag" "${assets[@]}" --clobber --repo "$GITHUB_REPOSITORY"
+          else
+            gh release create "$tag" "${assets[@]}" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "$tag" \
+              --generate-notes \
+              --notes "Published distributions and release metadata for $tag. See CHANGELOG.md for the reviewed release notes."
+          fi

{base_cli-0.4.2 → base_cli-0.4.3}/.github/workflows/tests.yml

@@ -65,10 +65,17 @@ jobs:
           python -m mypy --strict examples/typed_consumer.py
           python -m mypy --strict lib/python/base_cli
           python scripts/validate_docs.py
+          python scripts/validate_changelog.py
+          python scripts/validate_schemas.py
+          python scripts/validate_contract_fixtures.py
+          node scripts/validate_contract_fixtures.mjs
+          python scripts/generate_compatibility_dashboard.py --check
           python scripts/benchmark_runtime.py --check
           python -m compileall -q examples
       - name: Run tests with coverage threshold
-        run: python -m pytest --cov=base_cli --cov-report=term-missing --cov-fail-under=80
+        run: python -m pytest --cov=base_cli --cov-report=term-missing --cov-report=json:coverage.json --cov-fail-under=80
+      - name: Enforce high-risk module coverage floors
+        run: python scripts/validate_coverage.py coverage.json
       - name: Run static security checks
         run: |
           bandit -q -r lib/python/base_cli scripts -lll -iii

{base_cli-0.4.2 → base_cli-0.4.3}/CHANGELOG.md

@@ -11,6 +11,76 @@ and versions are tracked in the repo-root `VERSION` file.
 
 - Continue compatibility hardening and adoption work for the next release.
 
+## [0.4.3] - 2026-08-29
+
+This is a compatible pre-1.0 patch release. It contains lifecycle hardening,
+security fixes, versioned machine-readable contracts, and adoption tooling
+after 0.4.2; it does not introduce a new API or JSON-contract compatibility
+boundary. Existing Click and Typer command trees remain supported.
+
+### Changed
+
+- Add branch-aware coverage reporting with documented floors for lifecycle,
+  filesystem, compatibility, history, and contract modules.
+- Decompose the application implementation behind a compatibility facade into
+  focused core, lifecycle-installation, attachment, and invocation-runner
+  modules without changing the public import surface.
+- Bound the core Click and PyYAML dependency windows, publish the tested
+  compatibility matrix, and document the dependency update policy.
+- Validate Click 8.1 through 8.4 on the supported Python floor and ceiling,
+  and reject unvalidated Click 8.5+ versions through package metadata.
+- Move PyYAML behind the optional `base-cli[yaml]` extra and provide an
+  actionable installation hint when YAML configuration or output is selected.
+- Add an explicit `App.async_command()` adapter and `run_async()` helper for
+  deterministic async callbacks without changing the synchronous core.
+- Add versioned NDJSON output and typed writer protocols for bounded,
+  flush-per-record machine output.
+- Formalize typed extension callback protocols, entry-point capability metadata,
+  and pre-load API-version negotiation.
+
+### Security
+
+- Redact recognized secret keys embedded in query strings, comma-separated
+  values, and header-style `key: value` arguments before they reach logs or
+  persisted history.
+
+### Fixed
+
+- Keep the Typer adapter compatible with Typer 0.27.2's vendored exit
+  exception layout and validate that release in the compatibility matrix.
+- Apply the documented count-only 20-bundle retention default to implicit JSON
+  mode while preserving explicit retention policies, human-mode safe defaults,
+  and the `max_log_files` compatibility path.
+- Honor combined positive/negative JSON option declarations and explicit
+  `--no-json` values when deciding whether pre-parse errors use JSON output.
+- Isolate malformed third-party entry-point metadata so one invalid extension
+  cannot prevent healthy extensions from being discovered.
+
+### Added
+
+- Automate GitHub Releases from matching version tags with reviewed
+  distributions, checksums, SBOM metadata, and generated comparison notes.
+- Publish a generated dependency and platform compatibility dashboard linked
+  from the README and documentation site.
+- Add framework-specific migration guides for Click, Typer, Cement, and
+  `argparse`, with rollout and rollback checklists.
+- Add golden success, error, inspection, log, NDJSON, and command-protocol
+  fixtures with Python and Node.js validators for cross-language consumers.
+- Publish versioned JSON Schema artifacts for output, error, inspection, log,
+  NDJSON, and decoded command-protocol contracts in the package and docs site.
+- Add a framework choice guide, five-minute evaluation path, and clearer
+  production-lifecycle positioning for Click and Typer adopters.
+- Add deterministic SPDX SBOMs, artifact checksums, and OIDC-backed GitHub
+  attestations to protected release workflows.
+- Add a generated public API reference and a strict CI drift check so every
+  stable facade export remains searchable and documented.
+- Add a permissioned-adopter evidence policy and dated compatibility-run
+  artifacts without presenting maintained fixtures as customer adoption.
+
+- Align the README, documentation landing page, package metadata, and search
+  keywords around the production lifecycle layer positioning for Click and
+  Typer CLIs.
+
 ## [0.4.2] - 2026-08-08
 
 This is a compatible pre-1.0 patch release. It contains correctness fixes,
@@ -234,6 +304,14 @@ the API stability policy and migration guide before upgrading from `0.3.x`.
 - Initialized the repository with the Base-managed repo baseline.
 - Added the guarded package build, artifact validation, and protected
   TestPyPI/PyPI publication workflow.
+
+[Unreleased]: https://github.com/basefoundry/base-cli/compare/v0.4.3...HEAD
+[0.4.3]: https://github.com/basefoundry/base-cli/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/basefoundry/base-cli/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/basefoundry/base-cli/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/basefoundry/base-cli/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/basefoundry/base-cli/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/basefoundry/base-cli/releases/tag/v0.2.0
 - Exposed `base_cli.__version__` from the repository and installed package
   version contract.
 - Pinned the build backend to metadata compatible with the bundled publication

{base_cli-0.4.2 → base_cli-0.4.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: base-cli
-Version: 0.4.2
-Summary: A small, consumer-neutral Python CLI framework
+Version: 0.4.3
+Summary: The production lifecycle layer for Click and Typer Python CLIs
 Author: Base Foundry
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/basefoundry/base-cli
@@ -9,6 +9,7 @@ Project-URL: Repository, https://github.com/basefoundry/base-cli
 Project-URL: Issues, https://github.com/basefoundry/base-cli/issues
 Project-URL: Documentation, https://basefoundry.github.io/base-cli/
 Project-URL: Code of Conduct, https://github.com/basefoundry/base-cli/blob/main/CODE_OF_CONDUCT.md
+Keywords: cli,python-cli,command-line,command-line-interface,cli-framework,click,typer,framework,lifecycle,logging,structured-logging,configuration
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -23,15 +24,19 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Shells
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: click>=8.1
-Requires-Dist: PyYAML>=6.0
+Requires-Dist: click<8.5,>=8.1
+Provides-Extra: yaml
+Requires-Dist: PyYAML<7,>=6.0; extra == "yaml"
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: hypothesis<7,>=6.100; extra == "dev"
 Requires-Dist: mypy<2,>=1.17; extra == "dev"
+Requires-Dist: PyYAML<7,>=6.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
 Provides-Extra: typer
@@ -58,9 +63,18 @@ Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.2` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.2](https://github.com/basefoundry/base-cli/releases/tag/v0.4.2) |
+| `0.4.3` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.3](https://github.com/basefoundry/base-cli/releases/tag/v0.4.3) |
 
-`base-cli` is the PyPI distribution; import it in Python as `base_cli`.
+`base-cli` is the production lifecycle layer for Click and Typer Python CLIs.
+It standardizes context, logging, configuration, cleanup, and machine-readable
+contracts while leaving command and product policy in the consumer application.
+The PyPI distribution is `base-cli`; import it in Python as `base_cli`.
+
+It is for teams shipping operational CLIs that need the same diagnostics,
+configuration boundary, cleanup behavior, and automation contracts in every
+command. It is not a parser replacement or an application scaffold: Click and
+Typer still own parsing and command definitions, while the consuming project
+owns its domain policy and services.
 
 Install it with:
 
@@ -71,6 +85,11 @@ python -m pip install base-cli
 Read the complete documentation at
 <https://basefoundry.github.io/base-cli/>.
 
+Compatibility results and the permissioned-adopter policy are documented in
+the [adoption and compatibility evidence guide](https://basefoundry.github.io/base-cli/adoption-evidence/).
+The [compatibility dashboard](https://basefoundry.github.io/base-cli/compatibility-dashboard/)
+shows the declared and CI-tested dependency and platform support boundaries.
+
 ## Quick start
 
 Create a small command with a consistent context, logging, and cleanup
@@ -107,10 +126,9 @@ documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/relea
 The package is distributed under the Apache License 2.0. Base itself remains
 licensed separately under AGPL-3.0-or-later.
 
-`base_cli` is a small Python framework for writing command-line tools with
-a consistent lifecycle. It is designed to be embedded by applications rather
-than to define an application's project model. Base is one consumer of the
-library, not part of its generic contract.
+`base_cli` is designed to be embedded by applications rather than to define
+an application's project model. Base is one consumer of the library, not part
+of its generic contract.
 
 It is intentionally thin. Click still owns argument parsing and command
 execution, while `base_cli` provides reusable lifecycle behavior:
@@ -137,6 +155,8 @@ The supported public facade, compatibility promises, deprecation warning
 mechanism, and migration requirements are documented in
 [`docs/api-stability.md`](https://basefoundry.github.io/base-cli/api-stability/) and
 [`docs/migrations.md`](https://basefoundry.github.io/base-cli/migrations/).
+The complete generated facade is listed in the
+[`public API reference`](https://basefoundry.github.io/base-cli/api-reference/).
 
 Security reporting, runtime trust boundaries, threat assumptions, and the
 release security checklist are documented in [`SECURITY.md`](SECURITY.md),
@@ -283,6 +303,10 @@ catalog](examples/README.md). It covers a minimal command, nested/plugin Click,
 Typer, and automation/observability flows; each example has its own packaging,
 tests, completion, release, and troubleshooting guidance.
 
+Teams comparing frameworks can start with the [framework choice guide](docs/framework-choice.md),
+which explains what base-cli adds to Click or Typer and when a different
+framework is a better fit.
+
 Teams evaluating adoption can follow the [adopter readiness and migration
 guide](https://basefoundry.github.io/base-cli/adopter-readiness/) and run the three independent
 [downstream compatibility consumers](compatibility/README.md).
@@ -753,6 +777,10 @@ command execution as `130` without a traceback. After the command outcome has
 settled, history, metadata, and cleanup are best-effort teardown: even a second
 interrupt there cannot replace the primary result.
 
+Terminal lifecycle status is `ok` for exit code `0`, `aborted` for the
+interrupt exit code `130`, and `error` for other nonzero exit codes. The
+technical outcome remains precise: Ctrl+C is recorded as `interrupted`.
+
 An unexpected exception returns `1` with a stable, detail-free message. The run
 ID and diagnostic-log path are included when context and file logging are
 available. The traceback is kept in the persistent log when enabled and is
@@ -1106,8 +1134,9 @@ stdout or stderr for expected usage or application failures.
 
 `invoke()` sets `HOME` plus the relevant `USERPROFILE`, `LOCALAPPDATA`, and
 `XDG_CACHE_HOME` values when requested, and supplies `cwd` to the invocation for
-the duration of the test. Calls that use `cwd` are serialized and the caller's
-cwd is restored afterward, but this remains process-global: do not use it
+the duration of the test. All helper calls are serialized because `cwd` is
+process-global: a no-`cwd` call cannot observe another call's temporary
+directory, and the caller's cwd is restored afterward. Do not use it
 concurrently with code that changes cwd outside `invoke()` or from threads
 spawned by the invoked command. A generic profile should receive project
 fixtures through its `discover_project` callback. The helper does not create or

{base_cli-0.4.2 → base_cli-0.4.3}/README.md

@@ -7,9 +7,18 @@
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.2` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.2](https://github.com/basefoundry/base-cli/releases/tag/v0.4.2) |
+| `0.4.3` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.3](https://github.com/basefoundry/base-cli/releases/tag/v0.4.3) |
 
-`base-cli` is the PyPI distribution; import it in Python as `base_cli`.
+`base-cli` is the production lifecycle layer for Click and Typer Python CLIs.
+It standardizes context, logging, configuration, cleanup, and machine-readable
+contracts while leaving command and product policy in the consumer application.
+The PyPI distribution is `base-cli`; import it in Python as `base_cli`.
+
+It is for teams shipping operational CLIs that need the same diagnostics,
+configuration boundary, cleanup behavior, and automation contracts in every
+command. It is not a parser replacement or an application scaffold: Click and
+Typer still own parsing and command definitions, while the consuming project
+owns its domain policy and services.
 
 Install it with:
 
@@ -20,6 +29,11 @@ python -m pip install base-cli
 Read the complete documentation at
 <https://basefoundry.github.io/base-cli/>.
 
+Compatibility results and the permissioned-adopter policy are documented in
+the [adoption and compatibility evidence guide](https://basefoundry.github.io/base-cli/adoption-evidence/).
+The [compatibility dashboard](https://basefoundry.github.io/base-cli/compatibility-dashboard/)
+shows the declared and CI-tested dependency and platform support boundaries.
+
 ## Quick start
 
 Create a small command with a consistent context, logging, and cleanup
@@ -56,10 +70,9 @@ documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/relea
 The package is distributed under the Apache License 2.0. Base itself remains
 licensed separately under AGPL-3.0-or-later.
 
-`base_cli` is a small Python framework for writing command-line tools with
-a consistent lifecycle. It is designed to be embedded by applications rather
-than to define an application's project model. Base is one consumer of the
-library, not part of its generic contract.
+`base_cli` is designed to be embedded by applications rather than to define
+an application's project model. Base is one consumer of the library, not part
+of its generic contract.
 
 It is intentionally thin. Click still owns argument parsing and command
 execution, while `base_cli` provides reusable lifecycle behavior:
@@ -86,6 +99,8 @@ The supported public facade, compatibility promises, deprecation warning
 mechanism, and migration requirements are documented in
 [`docs/api-stability.md`](https://basefoundry.github.io/base-cli/api-stability/) and
 [`docs/migrations.md`](https://basefoundry.github.io/base-cli/migrations/).
+The complete generated facade is listed in the
+[`public API reference`](https://basefoundry.github.io/base-cli/api-reference/).
 
 Security reporting, runtime trust boundaries, threat assumptions, and the
 release security checklist are documented in [`SECURITY.md`](SECURITY.md),
@@ -232,6 +247,10 @@ catalog](examples/README.md). It covers a minimal command, nested/plugin Click,
 Typer, and automation/observability flows; each example has its own packaging,
 tests, completion, release, and troubleshooting guidance.
 
+Teams comparing frameworks can start with the [framework choice guide](docs/framework-choice.md),
+which explains what base-cli adds to Click or Typer and when a different
+framework is a better fit.
+
 Teams evaluating adoption can follow the [adopter readiness and migration
 guide](https://basefoundry.github.io/base-cli/adopter-readiness/) and run the three independent
 [downstream compatibility consumers](compatibility/README.md).
@@ -702,6 +721,10 @@ command execution as `130` without a traceback. After the command outcome has
 settled, history, metadata, and cleanup are best-effort teardown: even a second
 interrupt there cannot replace the primary result.
 
+Terminal lifecycle status is `ok` for exit code `0`, `aborted` for the
+interrupt exit code `130`, and `error` for other nonzero exit codes. The
+technical outcome remains precise: Ctrl+C is recorded as `interrupted`.
+
 An unexpected exception returns `1` with a stable, detail-free message. The run
 ID and diagnostic-log path are included when context and file logging are
 available. The traceback is kept in the persistent log when enabled and is
@@ -1055,8 +1078,9 @@ stdout or stderr for expected usage or application failures.
 
 `invoke()` sets `HOME` plus the relevant `USERPROFILE`, `LOCALAPPDATA`, and
 `XDG_CACHE_HOME` values when requested, and supplies `cwd` to the invocation for
-the duration of the test. Calls that use `cwd` are serialized and the caller's
-cwd is restored afterward, but this remains process-global: do not use it
+the duration of the test. All helper calls are serialized because `cwd` is
+process-global: a no-`cwd` call cannot observe another call's temporary
+directory, and the caller's cwd is restored afterward. Do not use it
 concurrently with code that changes cwd outside `invoke()` or from threads
 spawned by the invoked command. A generic profile should receive project
 fixtures through its `discover_project` callback. The helper does not create or

base_cli-0.4.3/VERSION

@@ -0,0 +1 @@
+0.4.3

{base_cli-0.4.2 → base_cli-0.4.3}/compatibility/README.md

@@ -1,9 +1,10 @@
 # Downstream compatibility consumers
 
-These are three independent, maintainable consumer fixtures used as adoption
-evidence until a non-Base team grants permission for a public case study. They
-are deliberately separate packages with separate names, entry points, and test
-suites; none imports another fixture or Base product code.
+These are three maintained reference consumer fixtures used as compatibility
+evidence. They are deliberately separate packages with separate names, entry
+points, and test suites; none imports another fixture or Base product code.
+They are not independent adopters and must not be presented as customer
+outcomes.
 
 | Consumer | Shape | Use case | Compatibility outcome |
 | --- | --- | --- | --- |
@@ -20,6 +21,12 @@ own dependencies, and runs each consumer's tests. This catches import,
 packaging, adapter, and contract regressions without relying on repository
 source imports.
 
+The downstream job records a dated JSON result as the
+`base-cli-compatibility-evidence-<run-id>` artifact. It binds the result to the
+framework revision and version and lists the exact fixture and matrix that
+passed. See [`adoption-evidence.md`](../docs/adoption-evidence.md) for the
+claim and permission boundary.
+
 The same workflow runs the Typer adapter and Beacon fixture against Typer
 0.25.1, 0.26.0, and 0.27.1 on Python 3.10 through 3.14. This matrix covers the
 transition from Click's public command classes to Typer's vendored Click fork.
@@ -35,4 +42,4 @@ for tests in compatibility/consumers/*/tests; do python -m pytest "$tests"; done
 ```
 
 The fixtures are not customer claims. A permissioned public adopter can be
-substituted in the manifest while retaining the same downstream contract tests.
+added as a separate record while retaining the same downstream contract tests.

{base_cli-0.4.2 → base_cli-0.4.3}/docs/adopter-readiness.md

@@ -11,7 +11,8 @@ Before the first production pilot, the adopter should be able to check every
 box below:
 
 - [ ] Pin a supported `base-cli` minor release (for example, `~=0.4.0`) and
-  record Click, PyYAML, and any optional integration versions in a lock file.
+  record Click, the optional YAML extra (when used), and any other integration
+  versions in a lock file.
 - [ ] Run the adopter's command suite on CPython 3.10--3.14 on every platform
   the product supports; retain at least one installed-wheel smoke job.
 - [ ] Use only the documented `base_cli` facade and module `__all__` exports;
@@ -72,18 +73,18 @@ release-blocking finding back to the compatibility register.
 
 ## Evidence and downstream compatibility
 
-The repository does not claim a customer identity without permission. Until an
-external team authorizes a public case study, three independent consumer
-fixtures provide the reviewable evidence:
+The repository does not claim a customer identity without permission. Three
+maintained reference fixtures provide compatibility evidence, but they are not
+independent adopters or customer outcomes:
 
 - **Atlas** — a Click inventory command migrated without rebuilding its tree;
 - **Beacon** — a typed Typer deployment command using the optional adapter; and
 - **Cinder** — a scheduled reconciliation command with dry-run and JSON output.
 
 Each fixture has its own package metadata and tests, is installed against the
-published framework wheel in CI, and records a stable invocation outcome. A
-permissioned adopter can replace a fixture with a public case study without
-changing the compatibility test contract.
+published framework wheel in CI, and records a stable invocation outcome. The
+[adoption and compatibility evidence](adoption-evidence.md) guide defines the
+permissioned adopter program and the public-claim boundary.
 
 ## Adoption friction and release gate