docs: clarify framework positioning and onboarding

CHANGELOG.md

@@ -11,6 +11,16 @@ and versions are tracked in the repo-root `VERSION` file.
 
 - Continue compatibility hardening and adoption work for the next release.
 
+### Added
+
+- Add a framework choice guide, five-minute evaluation path, and clearer
+  production-lifecycle positioning for Click and Typer adopters.
+
+### Changed
+
+- Improve PyPI description and search keywords to make the framework's
+  lifecycle, logging, configuration, and CLI integration surface discoverable.
+
 ## [0.4.2] - 2026-08-08
 
 This is a compatible pre-1.0 patch release. It contains correctness fixes,

README.md

@@ -9,7 +9,11 @@
 | --- | --- | --- | --- |
 | `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) |
 
-`base-cli` is the PyPI distribution; import it in Python as `base_cli`.
+`base-cli` is a production lifecycle framework for Python CLIs built with
+Click or Typer. 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`.
 
 Install it with:
 
@@ -56,10 +60,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:
@@ -232,6 +235,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).

docs/framework-choice.md

@@ -0,0 +1,45 @@
+# Framework choice guide
+
+`base-cli` is intentionally a lifecycle layer, not a replacement parser. The
+right choice depends on whether a project needs only argument parsing or also
+needs a repeatable operational contract around every invocation.
+
+## Comparison
+
+| Concern | Click | Typer | base-cli |
+| --- | --- | --- | --- |
+| Argument parsing and command trees | Core capability | Click-based, type-hint-friendly layer | Uses Click and can attach to Typer trees |
+| Consistent per-run context | Consumer-defined | Consumer-defined | `Context` carries paths, config, logging, and cleanup |
+| Logging and diagnostics | Application-defined | Application-defined | Structured stderr logging and persistent run metadata |
+| Configuration policy | Application-defined | Application-defined | Consumer-owned `CliProfile` boundary with optional batteries |
+| Cleanup and temporary state | Application-defined | Application-defined | Deterministic lifecycle hooks and per-run paths |
+| Machine-readable contracts | Application-defined | Application-defined | Versioned JSON and record/output contracts |
+| Best fit | A small or custom command surface | Typed Click applications | Production CLIs that need consistent operations across commands |
+
+This is a boundary comparison, not a feature-count ranking. Click and Typer
+remain the parser and command-definition choices; base-cli composes with them
+when the application also needs lifecycle, diagnostics, and compatibility
+contracts.
+
+## Five-minute evaluation
+
+1. Install the wheel in a clean environment:
+
+   ```bash
+   python -m pip install base-cli
+   ```
+
+2. Copy the [minimal command](https://github.com/basefoundry/base-cli/tree/main/examples/minimal_cli)
+   and run its test suite.
+
+3. Add one command-specific option and confirm that logs remain on stderr
+   while command output remains on stdout.
+
+4. Run the same command with `--debug` and `--keep-temp`, then inspect the
+   run context and retained log paths.
+
+5. If the application already uses Typer, install `base-cli[typer]` and
+   follow the [Typer adapter guide](typer-adapter.md).
+
+For a production migration checklist, continue with
+the [adopter readiness guide](adopter-readiness.md).

docs/index.md

@@ -5,6 +5,11 @@ professional command-line applications. It gives commands a consistent
 lifecycle, context, logging, cleanup, configuration, and test boundary while
 leaving application policy in the consuming project.
 
+In one sentence: **base-cli is the production lifecycle layer for a Click or
+Typer CLI**. It keeps parsing and command policy familiar while making the
+operational contract—context, logs, cleanup, configuration, and automation
+output—repeatable across commands.
+
 ## Quick start
 
 Install the package:
@@ -49,6 +54,8 @@ application.
 
 ## Choose a path
 
+- Use the [framework choice guide](framework-choice.md) to compare base-cli
+  with the underlying parser and decide whether its lifecycle boundary fits.
 - Start with the [adopter readiness guide](adopter-readiness.md) for a
   production evaluation.
 - Read [API stability](api-stability.md) and the [migration guide](migrations.md)

mkdocs.yml

@@ -31,6 +31,7 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Getting started:
+      - Framework choice: framework-choice.md
       - Adopter readiness: adopter-readiness.md
       - Platform support: platform-support.md
       - Consumer profiles: consumer-profiles.md

pyproject.toml

@@ -7,10 +7,20 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "base-cli"
 dynamic = ["version"]
-description = "A small, consumer-neutral Python CLI framework"
+description = "A production lifecycle framework for Click and Typer Python CLIs"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }
+keywords = [
+  "cli",
+  "command-line",
+  "click",
+  "typer",
+  "framework",
+  "lifecycle",
+  "logging",
+  "configuration",
+]
 authors = [
   { name = "Base Foundry" },
 ]