Refresh operator documentation and CLI help

examples/core/README.md

@@ -1,38 +1,70 @@
 # Core example
 
-Run the example from the repository root:
+This example shows typed flags, command shortcuts, shared reporting, and shell
+completion. It needs no external service. See the [consumer guide](../../docs/consumers/guide.md#go-compatibility)
+for Go requirements; maintainers use the toolchain in the
+[developer guide](../../docs/development.md#documentation-validation).
+
+Run from the repository root, with that Go toolchain on `PATH`:
 
 ```sh
+export GOWORK=off GOTOOLCHAIN=local
+go run ./examples/core workspace greet --count=2
+```
+
+The result shows the selected count and whether it was supplied. It also shows
+the entered command path and the original command path, which differ when you
+use a shortcut.
+
+## Try shortcuts and explicit values
+
+```sh
+# The hello shortcut runs workspace greet; --times means --count.
 go run ./examples/core hello --times=0 --tag=first
+# ws is a shortcut for the workspace group.
 go run ./examples/core ws greet --count=2
+# Inspect the group or use the example's global help alias.
 go run ./examples/core ws --help
 go run ./examples/core hello --hlep
+```
+
+An explicit zero remains a supplied value. The handler prints both
+`Invocation.EnteredPath()` and `Invocation.CanonicalPath()` so you can see how
+shortcuts resolve.
+
+## Try reporting
+
+```sh
+go run ./examples/core report
+go run ./examples/core report --verbose
+go run ./examples/core report --quiet
+```
+
+The default scenario succeeds and writes its result. Verbose mode also shows
+warnings and information; quiet mode hides the result. The
+[CLI reference](../../docs/cli.md#reporting) defines the shared visibility rules.
+
+## Try shell completion
+
+```sh
 go build -o core-example ./examples/core
 ./core-example completion bash
 ```
 
-The example installs a canonical `workspace greet` command together with a
-command shortcut, a group shortcut, a scoped flag alias, and a global help
-alias. Its declaration slice mixes the canonical group and routing rules as
-`[]commandkit.Declaration`. The handler prints `Invocation.EnteredPath()` and
-`Invocation.CanonicalPath()` so the alternate route and its canonical target
-are visible in the output.
+This prints the Bash completion script. Initialize `bash-completion`, then load
+the script as described in the [CLI reference](../../docs/cli.md#shell-completion).
+Use the executable basename `core-example` and try completing
+`core-example report d` or `core-example ws gr`. Other supported shells are
+listed in the reference.
 
-The example also installs `Completion("core-example")` and gives the `report`
-scenario argument static choices. Initialize `bash-completion` first if using
-Bash. Build it with the basename shown above, load
-the script for your shell using the [CLI reference](../../docs/cli.md#shell-completion),
-and try completing `core-example report d` or `core-example ws gr`.
+## How it is wired
 
-Compatible integration factories also return `commandkit.Command` and can be
-passed directly to `New` beside `commandkit.Alias` or flag-alias declarations.
-The matched ckconfig and ckprompt releases use the new core identity. For a
-command-only `[]commandkit.Command`, convert its elements into a
-`[]commandkit.Declaration` before appending routing rules; Go cannot expand the
-command slice as `...commandkit.Declaration`. The
+The example installs `workspace greet` alongside command and flag aliases in a
+`[]commandkit.Declaration`. It also installs `Completion("core-example")` and
+provides static choices for the reporting scenario argument. The
 [consumer guide](../../docs/consumers/guide.md#application-owned-aliases)
-shows both forms, and the [composed consumer](../../integrations/ckprompt/examples/composed)
-is the maintained integration example.
+explains declaration composition; the [composed example](../../integrations/ckprompt/examples/composed)
+adds integration commands.
 
-These aliases require core v0.3.0. Repository contributors can run its test with
-`go test ./examples/core` from the root.
+Run `GOWORK=off GOTOOLCHAIN=local go test ./examples/core` from the repository
+root to check this example.