docs: align positioning and discovery metadata (#236)

CHANGELOG.md

@@ -54,8 +54,9 @@ and versions are tracked in the repo-root `VERSION` file.
 - Add a permissioned-adopter evidence policy and dated compatibility-run
   artifacts without presenting maintained fixtures as customer adoption.
 
-- Improve PyPI description and search keywords to make the framework's
-  lifecycle, logging, configuration, and CLI integration surface discoverable.
+- 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
 

README.md

@@ -9,11 +9,16 @@
 | --- | --- | --- | --- |
 | `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 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`.
+`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:
 

docs/index.md

@@ -1,14 +1,14 @@
 # base-cli
 
-`base-cli` is a small, consumer-neutral Python framework for writing
-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.
+**base-cli is the production lifecycle layer for Click and Typer Python CLIs.**
+It gives commands a consistent lifecycle, context, logging, cleanup,
+configuration, and test boundary while leaving application policy in the
+consuming project.
+
+It is for teams shipping operational CLIs that need repeatable diagnostics and
+automation contracts across commands. 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.
 
 ## Quick start
 

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: base-cli
-site_description: A small, consumer-neutral Python framework for professional command-line applications.
+site_description: The production lifecycle layer for Click and Typer Python CLIs.
 site_url: https://basefoundry.github.io/base-cli/
 repo_name: basefoundry/base-cli
 repo_url: https://github.com/basefoundry/base-cli

pyproject.toml

@@ -7,18 +7,22 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "base-cli"
 dynamic = ["version"]
-description = "A production lifecycle framework for Click and Typer Python CLIs"
+description = "The production lifecycle layer for Click and Typer Python CLIs"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }
 keywords = [
   "cli",
+  "python-cli",
   "command-line",
+  "command-line-interface",
+  "cli-framework",
   "click",
   "typer",
   "framework",
   "lifecycle",
   "logging",
+  "structured-logging",
   "configuration",
 ]
 authors = [
@@ -39,6 +43,8 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+  "Topic :: System :: Shells",
 ]
 dependencies = [
   "click>=8.1,<9",