docs: add five-minute consumer quickstart (#351)

Fixes #344

Author: codeforester

docs/consumer-quickstart.md

@@ -0,0 +1,86 @@
+# Five-minute consumer quickstart
+
+This is the smallest useful `base-cli` application: one public `App`, one
+command, one option, and the `run_app()` process boundary. It is suitable for
+a temporary consumer project and does not require Typer, Rich, YAML, or any
+private repository layout.
+
+## Install and create the command
+
+Use an isolated virtual environment when trying the recipe. Activate it using
+the command appropriate for your shell, then install the core package:
+
+```bash
+python -m venv .venv
+python -m pip install base-cli
+```
+
+Create `hello.py`:
+
+```python
+from __future__ import annotations
+
+import base_cli
+
+
+app = base_cli.App(
+    name="hello",
+    lifecycle_options=base_cli.LifecycleOptions(
+        json=base_cli.LifecycleOption("--json"),
+    ),
+)
+
+
+@app.command()
+@base_cli.option("--name", default="world", show_default=True)
+def hello(ctx: base_cli.Context, name: str) -> int:
+    ctx.log.info("greeting %s", name)
+    print(f"Hello, {name}!")
+    return base_cli.ExitCode.SUCCESS
+
+
+if __name__ == "__main__":
+    raise SystemExit(base_cli.run_app(app))
+```
+
+The recipe uses only the public `base_cli` facade. Click remains the parser,
+while the consumer owns the command and its application behavior.
+
+## Run it in human mode
+
+```bash
+python hello.py --name Ada
+```
+
+The command prints `Hello, Ada!` on stdout. The greeting log is on stderr, so a
+consumer can redirect or suppress logs without corrupting command output.
+
+## Run the same command as JSON
+
+The recipe explicitly enables the optional lifecycle `--json` flag. Capture and
+parse the one JSON envelope like this:
+
+```bash
+python hello.py --json --name Ada > result.json
+python -m json.tool result.json
+```
+
+The success payload has `schema: "base-cli.output"`, `code: "ok"`, and a
+`details.stdout` string containing the command's human output. The `run_id` is
+runtime data and should not be hard-coded. Logs and diagnostics remain on
+stderr. See [JSON contracts](json-contracts.md) for the complete success,
+usage-error, and unexpected-error boundary.
+
+## What to validate
+
+The focused consumer checks are the two invocations above: confirm the human
+stdout and the JSON parse independently, and confirm that the process exit
+status is zero. For a repository change, run the focused documentation test
+with `python -m pytest tests/test_consumer_quickstart_docs.py` and run
+`git diff --check`.
+
+The core package requires Click and Python 3.10 or newer. Install
+`base-cli[yaml]` only when the consumer selects YAML configuration or output;
+Typer and other integrations are separate optional boundaries. See
+[dependency support](dependency-support.md) and [output contracts](output-contracts.md)
+before adding those integrations.

docs/index.md

@@ -56,6 +56,8 @@ application.
 
 - Use the [framework choice guide](framework-choice.md) to compare base-cli
   with the underlying parser and decide whether its lifecycle boundary fits.
+- Follow the [five-minute consumer quickstart](consumer-quickstart.md) for a
+  minimal public `App`, `run_app()`, human output, and JSON invocation.
 - Start with the [adopter readiness guide](adopter-readiness.md) for a
   production evaluation.
 - See the [adoption and compatibility evidence guide](adoption-evidence.md)

mkdocs.yml

@@ -33,6 +33,7 @@ nav:
   - Validation: testing.md
   - Getting started:
       - Framework choice: framework-choice.md
+      - Consumer quickstart: consumer-quickstart.md
       - Adopter readiness: adopter-readiness.md
       - Adoption evidence: adoption-evidence.md
       - Compatibility dashboard: compatibility-dashboard.md

scripts/validate_docs.py

@@ -19,6 +19,7 @@
         "cache-ownership-and-layout.md",
         "compatibility-dashboard.md",
         "consumer-profiles.md",
+        "consumer-quickstart.md",
         "coverage-policy.md",
         "dependency-support.md",
         "extensions.md",

tests/test_consumer_quickstart_docs.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+ROOT = Path(__file__).parents[1]
+DOC = ROOT / "docs" / "consumer-quickstart.md"
+INDEX = ROOT / "docs" / "index.md"
+VALIDATOR = ROOT / "scripts" / "validate_docs.py"
+
+
+def test_consumer_quickstart_is_linked_from_the_documentation_index() -> None:
+    assert "consumer-quickstart.md" in INDEX.read_text(encoding="utf-8")
+    assert "consumer-quickstart.md" in VALIDATOR.read_text(encoding="utf-8")
+
+
+def test_consumer_quickstart_uses_only_public_apis_and_explains_both_modes() -> None:
+    text = DOC.read_text(encoding="utf-8")
+
+    for required in (
+        "base_cli.App",
+        "base_cli.LifecycleOptions",
+        'base_cli.LifecycleOption("--json")',
+        "base_cli.run_app(app)",
+        "python hello.py --name Ada",
+        "python hello.py --json --name Ada",
+        "base-cli.output",
+        "dependency-support.md",
+        "output-contracts.md",
+    ):
+        assert required in text