From d0eb13abc11bd6d83ee7d88ff4565ee2de7aab9b Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Fri, 28 Aug 2026 11:43:44 +0530
Subject: [PATCH] docs: align positioning and discovery metadata (#236)

---
 CHANGELOG.md   |  5 +++--
 README.md      | 15 ++++++++++-----
 docs/index.md  | 18 +++++++++---------
 mkdocs.yml     |  2 +-
 pyproject.toml |  8 +++++++-
 5 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0dcc27..8716a27 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/README.md b/README.md
index 602d1a3..1034acc 100644
--- a/README.md
+++ b/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:
 
diff --git a/docs/index.md b/docs/index.md
index 373abf2..f34156a 100644
--- a/docs/index.md
+++ b/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
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 126bb5b..9baffab 100644
--- a/mkdocs.yml
+++ b/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
diff --git a/pyproject.toml b/pyproject.toml
index 7a0d782..1e8264b 100644
--- a/pyproject.toml
+++ b/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",