Complete CommandKit consumer documentation

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).