Complete CommandKit consumer documentation

docs/cli.md

@@ -233,7 +233,7 @@ and asks PromptKit to inspect the named definition. Inspection reads the
 engine's captured configuration; it does not generate a prompt, contact a
 provider, or look up credentials.
 Prompt definitions and profile resolution remain owned by
-[PromptKit](https://pkg.go.dev/gitea.maximumdirect.net/eric/promptkit).
+[PromptKit's inspection API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/engine.go).
 
 ```text
 example promptkit show prompt customer/summary --version 2 --format yaml

docs/consumers/guide.md

@@ -0,0 +1,74 @@
+# Consumer guide
+
+CommandKit's supported Go API is the root `commandkit` package. Start with an
+`App`, register CommandKit's standard inspection families, register application
+commands, and call `App.Execute` with the caller's context and streams. The
+caller retains process startup, signal handling, and exit mapping.
+
+## A configuration scope
+
+Use [`NewConfigKitScope`](../../config.go) to adapt one ConfigKit loader. The
+loader receives the invocation's explicit `Selection`; the application decides
+how those supplied config and overlay values map to its inputs.
+
+```go
+scope, err := commandkit.NewConfigKitScope[appContext, appConfig](
+	"app",
+	"Application settings.",
+	func(ctx context.Context, selection commandkit.Selection, app appContext) (*configkit.Result[appConfig], error) {
+		return loadAppConfig(ctx, selection, app)
+	},
+)
+if err != nil {
+	return err
+}
+err = commandkit.RegisterConfig(app, commandkit.ConfigSuite[appContext]{
+	Scopes: []commandkit.ConfigScope[appContext]{scope},
+})
+```
+
+`config show`, `config sources`, and `config explain` use the configuration
+captured by that load. A scope can support only the operations it provides.
+When several scopes share invocation-local application state, create it in
+`ConfigSuite.NewContext`; use typed `Selector` bindings to copy only the values
+that apply to each scope. See the [composed example](../../examples/composed/README.md)
+for a cache shared by the `app` and `promptkit` scopes.
+
+## PromptKit configuration and definitions
+
+Register `NewPromptKitScope` with the config suite when you want the effective
+PromptKit configuration and its ConfigKit provenance available under `config`.
+Register `NewPromptKitSuite` and `RegisterPromptKit` separately to enable
+`promptkit show prompt` and/or `promptkit show profile`. Each adapter calls the
+owning public inspection method and preserves acquisition diagnostics with a
+failed named lookup. Definition inspection does not invoke execution APIs or
+resolve provider credentials.
+
+The [composed example](../../examples/composed/README.md) shares its ordinary app and
+engine-loading functions across the configuration and definition suites. It
+also keeps `session restore` as an application-owned typed command, including
+its session data and domain outcome mapping.
+
+## Typed application commands
+
+Declare flags, operands, and a typed input struct with `NewCommand`. Bindings
+preserve whether a value was explicitly supplied, so an explicit zero can differ
+from an omitted default. `RepeatFlag` retains occurrence order. The
+[simple example](../../examples/simple/README.md) combines both features with a typed
+ConfigKit scope.
+
+## Outcomes and process exit
+
+Handlers return `Success`, `Failure`, or an application-owned `Outcome`. The
+caller chooses how a nonzero status maps to process exit; `Execute` never exits
+the process. It writes CommandKit diagnostics to the supplied error stream and
+returns the resulting classification and delivery information. Applications
+keep their domain meanings and output in their own handlers.
+
+Exact CommandKit contracts are documented on the exported declarations and
+their GoDoc comments. ConfigKit owns configuration decoding and provenance;
+consult its [inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/inspection.go).
+PromptKit owns prompt formats and profile resolution; consult its [public
+engine methods](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/engine.go),
+[configuration inspection](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/configuration_inspection.go),
+and [inspection types](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/types.go).

docs/development.md

@@ -4,10 +4,10 @@ CommandKit currently contains adopted repository policies, accepted architectura
 decisions, implementation plans, identity and outcome primitives, typed command
 declarations, an instance-owned registry, a Cobra-backed routing and parsing
 adapter, public `App.Execute` coordination, and generated help/version commands.
-Configuration suite registration, scope discovery, ConfigKit integration,
-validation, native effective YAML display, source inventory, and path
-explanation reports, PromptKit engine configuration inspection, and optional
-PromptKit prompt/profile inspection commands are implemented. The
+Configuration suite registration, scope discovery, ConfigKit validation and
+reports, PromptKit engine configuration inspection, and optional PromptKit
+prompt/profile inspection commands are implemented. The maintained
+[consumer guide](consumers/guide.md) links to maintained examples. The
 [README](../README.md) provides project orientation; the
 [documentation policy](policy/documentation.md#canonical-ownership) assigns
 canonical documentation owners.
@@ -87,3 +87,19 @@ Follow the [local commit policy](policy/agents.md#git-commit-policy). Completed
 units receive local commits by default, subject to explicit user instructions.
 Preserve unrelated work; default commit authorization does not authorize pushing
 or publishing.
+
+## Current public examples
+
+The maintained consumers under `examples/` compile with the module suite and
+run without external services:
+
+```sh
+go run ./examples/simple config show
+go run ./examples/simple greet --count=0 --tag=first --tag second
+go run ./examples/composed config validate --scope all --campaign spring
+go run ./examples/composed promptkit show prompt briefing --campaign spring --format yaml
+go run ./examples/composed session restore session-42 --campaign spring
+```
+
+The [consumer guide](consumers/guide.md) explains how their public API usage
+fits together.

docs/internal/overview.md

@@ -0,0 +1,36 @@
+# Internal package overview
+
+CommandKit ships one public package, `commandkit`, and one internal package,
+`internal/cobra`. This inventory describes the current implementation; the
+[architecture policy](../policy/architecture.md) owns normative boundaries and
+[ADR 0003](../adr/0003-public-facade.md) records the public package boundary.
+
+## `commandkit`
+
+The root package declares the public API and owns the instance registry, typed
+command input preparation, invocation coordination, standard handlers, and
+provider adapters. Configuration reports adapt ConfigKit's public records and
+writers. PromptKit scope and definition handlers use PromptKit's public
+inspection methods and map their results to CommandKit-owned reports.
+
+The root package imports `internal/cobra` to bridge its command declarations and
+invocations to Cobra parsing and routing. Application callbacks, output streams,
+context, and supported error identity cross that bridge through the root's typed
+contracts.
+
+## `internal/cobra`
+
+This package owns the Cobra-specific command tree and argument/flag parsing
+adapter. It translates neutral command metadata and parsed values into a bridge
+result consumed by the root package. It does not import `commandkit` and does not
+own registry policy, public command declarations, provider loading, or report
+rendering.
+
+## External implementation boundaries
+
+ConfigKit owns typed configuration loading, source history, validation,
+resolution, and path explanations. PromptKit owns captured engine
+configuration, prompt definitions, profile inheritance, and named inspections.
+CommandKit depends on their public module APIs and does not maintain parallel
+schemas. Cobra and pflag are confined behind the internal adapter; YAML report
+encoding is performed by the root package.

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Initial CommandKit implementation plan
 
-Status: implementation underway; Stages 1-13 complete and Stage 14 pending.
+Status: implementation complete; Stages 1-14 complete.
 
 Date: 2026-10-07.
 
@@ -818,7 +818,7 @@ selection errors, optional capabilities, and help without engine construction.
 
 ## Stage 14: substantiate consumer fit and complete documentation
 
-**Status:** pending. **Prerequisite:** Stage 13.
+**Status:** complete. **Prerequisite:** Stage 13.
 
 1. Add complete maintained examples using only the public root API and published
    upstream packages. Use two ordinary example directories (separate Go main
@@ -860,8 +860,12 @@ selection errors, optional capabilities, and help without engine construction.
    into the implementation. Record completed stage status and checks, then commit
    the completed unit under the local policy. Publishing remains separate work.
 
-**Completion evidence:** each included roadmap feature has observable behavior
-and its appropriate checks; examples compile and use the real public dispatcher;
-default tests do not require real services/credentials; documents describe only
-implemented contracts. The final report identifies the commits, checks, and
-deferred capabilities without claiming downstream migrations or release completion.
+**Completion evidence:** added maintained `examples/simple` and
+`examples/composed` consumers, public consumer guidance, internal architecture
+overview, and updated CLI/development/README/feature-roadmap documentation. The
+examples compile and use the public dispatcher with synthetic data. Shared
+selector helpers serve both configuration suites. Reviewed exported declarations,
+root and adapter imports, dependency replacements, attribution, and retained
+deferred feature IDs. Verified with `gofmt`, `go test ./...`, `go mod tidy -diff`,
+document link checks, example smoke commands, and `git diff --check`. Publishing,
+downstream migrations, and deferred capabilities remain outside this stage.

docs/roadmap/initial.md

@@ -1,16 +1,25 @@
 # Initial CommandKit feature roadmap
 
-Status: selected initial implementation target; unimplemented.
+Status: selected initial implementation target; implemented.
 
 Date: 2026-10-07.
 
 ## Purpose and authority
 
-This document defines the selected end state of the initial library: packages,
-features, integration contracts, dependencies, and completion evidence. It is
-prepared using [the agreed checklist](initial-plan.md). Implementation steps belong
-in [the implementation plan](implementation.md). This document describes the target
-state; CommandKit currently has no Go module or dispatcher implementation.
+This document defines the selected initial target for the library: packages,
+features, integration contracts, dependencies, and completion evidence. It was
+prepared using [the agreed checklist](initial-plan.md). Implementation steps and
+stage evidence belong in [the implementation plan](implementation.md). The
+included target is implemented; the table below records feature status.
+
+| Included feature IDs | Status | Evidence |
+| --- | --- | --- |
+| API-01, REG-01, INPUT-01, BACK-01, INV-01, OUT-01 | complete | Root API and dispatcher tests; `go test ./...`. |
+| HELP-01, VER-01 | complete | Help/version behavior tests; `go test ./...`. |
+| INT-01, CFG-01–05 | complete | Configuration scope, validation, show, sources, and explain tests; `go test ./...`. |
+| PK-01 | complete | PromptKit scope adapter tests; `go test ./...`. |
+| PK-02, PK-03 | complete | Prompt/profile inspection tests; `go test ./...`. |
+| DIFF-01, CAT-01 | deferred | Require upstream safe snapshot and catalog APIs; see [deferred capability targets](#deferred-capability-targets). |
 
 The [architecture policy](../policy/architecture.md) and nine accepted ADRs control
 this roadmap. The delivery scope, typed API model, selector/report behavior, and
@@ -63,11 +72,10 @@ module still declares the dependencies used by its bundled helpers.
 | PromptKit definitions | `promptkit show prompt` and `promptkit show profile`, including effective `ExtraParams` |
 | Application commands | Typed custom leaf commands, nested groups, and groups with their own runnable handler |
 
-Defer catalog listing and semantic comparison until the owning libraries expose
-the required public contracts. These accepted standard operations remain future
-implementation targets. Their absence must appear accurately in help and
-capabilities. Initial delivery uses the current released inspection APIs; upstream
-snapshot/catalog enhancements are separate follow-up work.
+Catalog listing and semantic comparison remain deferred until the owning
+libraries expose the required public contracts. Their absence appears accurately
+in help and capabilities. The implemented target uses the released inspection
+APIs; upstream snapshot/catalog enhancements are separate follow-up work.
 
 This scope provides meaningful configuration inspection immediately and avoids
 requiring an initial consumer migration to wait for every future capability.