Refresh operator documentation and CLI help

integrations/ckconfig/examples/simple/README.md

@@ -1,37 +1,90 @@
-# Simple consumer
+# ConfigKit example
 
-This example imports `go.maximumdirect.net/ckconfig` and
-`go.maximumdirect.net/commandkit`; ckconfig v0.4.0 uses core
-v0.4.0, ConfigKit v1.1.0, and Go 1.27.0. Set `GOWORK=off GOTOOLCHAIN=local`
-for the commands below.
+This example adds configuration inspection and a custom `greet` command to a
+small application. It uses local fixtures and in-memory defaults, with no
+external services. See [module selection](../../../../docs/consumers/guide.md#module-selection)
+for dependencies and Go requirements. Use Go 1.27.0 on `PATH` for this checkout.
 
-Run the maintained example with:
+From the repository root:
 
 ```sh
+cd integrations/ckconfig/examples/simple
+export GOWORK=off GOTOOLCHAIN=local
 go run . config show
-go run . config show --config fixtures/before.yml --verbose
-go run . config show --config fixtures/before.yml --quiet
+```
+
+The output includes the default greeting, `Hello`, and schema version 2.
+This example can run against its declared released dependencies with the
+workspace disabled.
+
+## Inspect and override a value
+
+```sh
+# Discover configuration paths under schema.
 go run . config explain --list --under /schema
+# Change the greeting for this invocation and show just that value.
 go run . config show --path /greeting --set '/greeting="Hi"'
+```
+
+The second command prints `Hi`. It does not edit a file.
+
+## Compare configurations
+
+```sh
 go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml
+```
+
+The report includes `changes.greeting: Goodbye`.
+
+```sh
+# Expected status 3: the overridden greeting differs from the ordinary default.
 go run . config diff --set '/greeting="Hi"' --details --check
+```
+
+This compares the overridden left side with ordinary configuration on the
+right. `go run` prints `exit status 3` and itself exits with status 1; a built
+executable returns the application's status 3 directly.
+
+## Inspect warnings and failed loads
+
+```sh
+# Schema version 1 produces a warning, visible in verbose mode.
+go run . config show --config fixtures/before.yml --verbose
+# Quiet mode hides the configuration report and warning.
+go run . config show --config fixtures/before.yml --quiet
+```
+
+Ordinary mode hides the warning but still displays configuration.
+
+```sh
+# Intentional failure: show detailed validation findings for the invalid fixture.
 go run . config validate --config fixtures/invalid.yml --details --severity error
+# Intentional failure: still show the source recorded before loading failed.
 go run . config sources --config fixtures/invalid.yml --source-id source-1
+```
+
+Both commands retain the load failure. `source-1` belongs to this fixture's
+load; other configurations can have different source IDs. See the
+[CLI reference](../../../../docs/cli.md#configuration-scopes) for report and status rules.
+
+## Try a custom command
+
+```sh
 go run . greet
 go run . greet --count=0 --tag=first --tag second
 ```
 
-The `config` family comes from one typed ConfigKit scope. The custom `greet`
-command uses CommandKit's typed bindings and shows the difference between an
-omitted `--count` and an explicitly supplied zero, plus ordered repeated tags.
-With no `--config`, application settings use the in-memory default. A supplied
-configuration and overlay are passed to ConfigKit unchanged. The comparison
-command loads the two local fixtures and reports `changes.greeting: Goodbye`.
-The before fixture uses schema version 1, which ConfigKit reports as a provider
-warning in verbose mode. Ordinary mode hides the warning while preserving the
-effective YAML report; quiet mode suppresses that report.
-The invalid fixture demonstrates a failed-load report and captured source
-inventory; `source-1` is the ID from that fixture's acquisition. The scope opts
-in to transient overrides and passes them into its normal ConfigKit load. The
-diff example compares an overridden left side with ordinary configuration on
-the right and returns status 3 because the values differ.
+The handler reports its greeting, count, and tags. It distinguishes an omitted
+count from an explicitly supplied zero and preserves repeated tag order.
+
+## How it is wired
+
+One ConfigKit scope supplies the standard `config` commands. Without `--config`,
+its loader uses an in-memory default. Supplied configuration and overlay values
+are passed to ConfigKit unchanged. The scope enables temporary overrides and
+passes them into its ordinary ConfigKit load. The
+[consumer guide](../../../../docs/consumers/guide.md#configkit-scopes) explains
+loader and scope setup.
+
+Run `GOWORK=off GOTOOLCHAIN=local go test ./...` from this example directory to
+check it against its declared dependencies.