docs: explain the value Base-CLI adds to a consumer

README.md

@@ -9,6 +9,22 @@ command tree, domain policy, and local data model.
 Northstar does not require Base, Docker, cloud credentials, or network access
 after its dependencies are installed.
 
+## Why base-cli?
+
+Click gives Northstar its command tree; Base-CLI adds the shared work around
+each invocation so the application does not have to build and maintain its own
+logging lifecycle, runtime paths, cleanup hooks, and machine-output contract.
+That is useful when a CLI is used by both people and automation, especially
+when commands need predictable JSON, actionable errors, safe diagnostics, or
+dry-run behavior. For a one-off command without those needs, plain Click may be
+the simpler choice.
+
+In this demo, [`src/base_cli_demo/cli.py`](src/base_cli_demo/cli.py) owns the
+Northstar commands and service policy. Its `base_cli.App`, `app.attach(...)`,
+and `base_cli.run_app(...)` wiring delegates the invocation lifecycle to the
+framework; `status` and `release reconcile` show that boundary in use. See the
+[full value and responsibility map](docs/why-base-cli.md).
+
 ## Quick start
 
 From a fresh checkout:

docs/why-base-cli.md

@@ -0,0 +1,43 @@
+# Why base-cli?
+
+Every CLI application chooses how to define commands. A production CLI also
+needs a repeatable contract around each command: where logs go, how errors map
+to exit status, where temporary and run data live, how cleanup runs, and how
+automation requests structured output. Without a shared lifecycle layer, each
+application decides, implements, and tests those details for itself.
+
+Base-CLI composes with Click (and can attach to Typer); it is not a replacement
+parser. It supplies the invocation lifecycle and public output/runtime APIs,
+while the consumer keeps its command tree, configuration policy, and domain
+behavior.
+
+| Shared concern | Northstar example | What the framework supplies |
+| --- | --- | --- |
+| Human and machine output | `northstar status --format json` | Public record renderers and stable JSON records. |
+| Automation envelope | `northstar --json status --format json` | A versioned success/error envelope and the command's exit status. |
+| Safe state-changing workflow | `northstar --dry-run release reconcile` | A lifecycle dry-run flag and consistent invocation context; Northstar decides what its local demo operation means. |
+| Diagnostics | `northstar --debug --log-file ... release reconcile` | Lifecycle logging, log placement, and registered sensitive-argument redaction. |
+| Per-run files and cleanup | `release reconcile` | Managed runtime/temp paths and cleanup hooks; Northstar owns its state record. |
+
+## What would otherwise be hand-written
+
+The small consumer entry point in [`src/base_cli_demo/cli.py`](../src/base_cli_demo/cli.py)
+still owns the Click command tree and domain behavior. Without Base-CLI, that
+same file would also need to hand-write and test the surrounding lifecycle:
+
+- turn `--environment`, `--dry-run`, `--json`, `--debug`, `--log-file`, and
+  `--keep-temp` into a consistent invocation context;
+- choose state and temporary directories, run cleanup callbacks, and preserve
+  the dry-run boundary around `release reconcile`;
+- route records through text/JSON/CSV/TSV/NDJSON output and emit the structured
+  success/error envelope used by automation; and
+- configure logging, redact `approval_token`, and map command failures to stable
+  exit status.
+
+Those are the production-shaped behaviors supplied by Base-CLI and exercised
+through its public facade. Northstar still decides its service fixture schema,
+environment selection, target-version policy, and the meaning of
+`release reconcile`; those decisions remain in the Click commands and
+[`src/base_cli_demo/profile.py`](../src/base_cli_demo/profile.py). The README's
+[framework boundary](../README.md#framework-boundary) is the concise ownership
+summary.