Document PromptKit comparison and catalogs

README.md

@@ -16,7 +16,7 @@ constructing them, and returns outcomes without exiting the process. Its
 | --- | --- | --- |
 | `gitea.maximumdirect.net/eric/CommandKit` | `commandkit` | Typed commands, bindings, execution, outcomes, help, and version. |
 | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes and inspection commands. |
-| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration and optional named prompt/profile inspection. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, prompt/profile catalogs, and named inspection. |
 
 Importing an integration does not install commands. Pass its declaration to
 `commandkit.New` or `App.Register` to install it. The integrations depend on the

docs/cli.md

@@ -106,8 +106,9 @@ declared scope capabilities and installed handlers, so an operation is listed
 only when the corresponding command is available.
 
 Applications can add `ckprompt.ConfigScope(loadEngine)` to the ConfigKit suite
-to expose PromptKit engine configuration through these handlers. This scope
+to expose PromptKit engine configuration through these handlers. The scope
-does not install PromptKit prompt or profile definition commands.
+declares validate, show, sources, explain, and native diff. It does not install
+PromptKit prompt or profile definition commands.
 
 ### Validate configuration
 
@@ -235,8 +236,11 @@ serialized as `[]`.
 `config diff` prepares two selections for one scope that declares comparison
 and invokes its comparison provider after input checks pass. The default scope
 is `app`; `--scope all` is unsupported.
-The PromptKit engine scope does not currently declare comparison, so selecting
+When an application installs `ckprompt.ConfigScope(loadEngine)`, the PromptKit
-`--scope promptkit` is a usage error.
+scope declares comparison and delegates it to PromptKit's captured
+configuration inspection API. PromptKit owns the meaning of that native
+comparison; CommandKit uses the existing `config diff` preparation and report
+path.
 `--config` and `--overlay` select the left side. `--against-config` and
 `--against-overlay` independently override the right side. When a right-side
 field is omitted, it inherits the corresponding left value and supplied state;
@@ -250,21 +254,24 @@ YAML is the only format and the default. Explicit `--format yaml` is accepted;
 example config diff --config before.yml --against-config after.yml
 example config diff --config base.yml --against-overlay candidate
 example config diff --config base.yml --overlay current --against-overlay ""
+example config diff --scope promptkit --config before.yml --against-config after.yml
 ```
 
-ConfigKit compares frozen effective typed values after defaults and resolution;
+For ConfigKit-backed scopes, ConfigKit compares frozen effective typed values
-source or provenance differences alone do not create a change. The report is one
+after defaults and resolution; source or provenance differences alone do not
-YAML document with `additions`, `changes`, and `deletions` in that order.
+create a change. PromptKit delegates its native comparison to ConfigKit. The
-Additions and changes preserve semantic paths and contain safe right-side values.
+report is one YAML document with `additions`, `changes`, and `deletions` in that
-Deletions contain canonical JSON Pointer paths. Explicit null is a value; it is
+order. Additions and changes preserve semantic paths and contain right-side
-not a deletion. Changed sequences and native structural replacement regions stay
+values provided by the native comparison. Deletions contain canonical JSON
-atomic.
+Pointer paths. Explicit null is a value; it is not a deletion. Changed sequences
+and native structural replacement regions stay atomic.
 
 ConfigKit pairs sensitivity across both loads. A concealed change can therefore
-appear even when its two safe snapshots are equal. The report omits separate
+appear even when its two safe snapshots are equal. For those ConfigKit-backed
-redaction and hidden-change metadata: a reported masked region changed, but that
+comparisons, the report omits separate redaction and hidden-change metadata: a
-does not mean every member inside it changed. Marker-looking public strings stay
+reported masked region changed, but that does not mean every member inside it
-ordinary YAML values. An empty comparison succeeds with this shape:
+changed. Marker-looking public strings stay ordinary YAML values. An empty
+comparison succeeds with this shape:
 
 ```yaml
 additions: {}
@@ -277,7 +284,7 @@ automatically applicable patch. Exceptional whole-root empty/null transitions
 can be ambiguous because the report has no root envelope; ordinary field-level
 null values and deletions retain their distinction.
 
-Successful comparisons return status `0`, including concealed or empty results.
+Successful comparisons return status `0`, including empty results.
 Unsupported scopes and format errors are usage errors; input checks retain the
 existing usage/operational classification. Load and native comparison failures
 are operational and preserve supported error identity.
@@ -375,6 +382,43 @@ error identity. Cancellation is also operational: standard handlers check the
 caller's context at inspection boundaries, and PromptKit can return cancellation
 from its own inspection methods. Supported cancellation identity is preserved.
 
+### PromptKit catalogs
+
+An installed `ckprompt.Command(suite)` exposes the catalog commands supplied by
+the suite:
+
+```text
+example promptkit list prompts
+example promptkit list profiles --config settings.yml --campaign spring
+```
+
+Each command accepts `--config`, `--overlay`, and applicable selectors from
+`Suite.Selectors`. It takes no ID or version operand and has no `--version` or
+`--scope` selector. `--format` defaults to `yaml`; `--format yaml` is accepted,
+and other formats are usage errors.
+
+Each invocation writes one bare YAML sequence. Prompt entries have explicit
+string `id` and `version` fields; profile entries are strings. Provider order and
+exact identity values are preserved. For example:
+
+```yaml
+- id: briefing
+  version: "1"
+- id: briefing
+  version: "2"
+```
+
+```yaml
+- autumn
+- spring
+```
+
+Successful nil and allocated-empty inventories both render as `[]`. Catalog
+membership and ordering follow the selected provider, and a listed definition
+is not a readiness check or execution result. PromptKit owns the meaning of its
+native listing APIs; custom providers own their results. Applications retain
+their own disclosure choices for catalog data.
+
 ## Outcome status
 
 CommandKit usage failures use status `2`; operational failures use status `1`.

docs/consumers/guide.md

@@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`.
 | --- | --- |
 | `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. |
 | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
-| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration or named prompt/profile inspection. |
+| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, or named inspection. |
 
 The two integrations are independent optional imports. `ckprompt` uses the
 public scope and error contracts from `ckconfig`; importing it does not add the
@@ -123,29 +123,41 @@ owns operator syntax and report details.
 
 `ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
 engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
-it under `config`; it does not install named definition commands.
+it under `config` with validate/show/sources/explain and native diff operations;
+it does not install named definition commands.
 
-`ckprompt.FromEngine(loadEngine)` supplies PromptKit named prompt and profile
+`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks
-inspection callbacks. Set its `NewInput`, `NewState`, selectors, or validation
+and named inspection callbacks. Set its `NewInput`, `NewState`, selectors, or
-when the application needs them, then pass `ckprompt.Command(suite)` to core.
+validation when the application needs them, then pass `ckprompt.Command(suite)`
-Prompt and profile capabilities can be installed independently by providing
+to core. The four callbacks are independently optional; `Command` creates `list`
-only the corresponding callback. Each selected inspection prepares one input
+and `show` groups only when their corresponding callbacks are present. Narrow a
-and one state value when those steps are reached. See
+bundled suite before command capture when the application wants catalogs without
+named inspections:
+
+```go
+definitions := ckprompt.FromEngine(loadEngine)
+definitions.InspectPrompt = nil
+definitions.InspectProfile = nil
+definitionCommand := ckprompt.Command(definitions)
+```
+
+Each selected inspection or catalog operation prepares one input, applies its
+captured selectors, checks that input, and initializes one state value when
+those steps are reached. See
 [ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
 timing, omitted-factory zero values, and caller-owned objects and effects.
 The loader receives invocation context, explicitly supplied selection, input,
-and state. The adapter
+and state. The adapter uses PromptKit's public listing and inspection methods
-uses PromptKit's public inspection methods and preserves acquisition diagnostics
+and preserves acquisition diagnostics and supported error identity.
-and error identity.
 
-CommandKit-owned inspection code does not execute prompts, contact model
+CommandKit-owned listing and inspection code does not execute prompts, contact model
 providers, or resolve credential values; application loaders and direct callbacks
 retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
-owns the inspection boundary and credential-report semantics.
+owns the command and report contracts.
 
 The [composed example](../../integrations/ckprompt/examples/composed/README.md)
-combines app and PromptKit config scopes, independently registers profile
+combines app and PromptKit config scopes, comparison and catalogs, named
-inspection, and adds an application-owned `session restore` command.
+inspection, and an application-owned `session restore` command.
 
 ## Outcomes and ownership
 

docs/development.md

@@ -137,6 +137,9 @@ go run ./examples/core workspace greet --count=0 --tag=first --tag second
 (cd integrations/ckconfig/examples/simple && go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml)
 (cd integrations/ckprompt/examples/composed && go run . config validate --scope all --campaign spring --limit=0)
 (cd integrations/ckprompt/examples/composed && go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml)
+(cd integrations/ckprompt/examples/composed && go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
+(cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
 (cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
 (cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
 ```

docs/internal/overview.md

@@ -47,10 +47,11 @@ initialized input, while one suite-owned state value is shared by an invocation'
 acquisitions or comparison callback.
 
 `integrations/ckprompt` owns PromptKit engine loading, configuration-scope
-adaptation, and optional named prompt/profile inspection. It uses public core
+adaptation and native comparison, plus optional prompt/profile catalogs and
-and ckconfig contracts plus PromptKit's public APIs. It does not add a
+named inspection. It uses public core and ckconfig contracts plus PromptKit's
-configuration family when its declaration is installed; callers compose
+public APIs. It does not add a configuration family when its declaration is
-`ckprompt.ConfigScope` with `ckconfig.Command` separately when they want both.
+installed; callers compose `ckprompt.ConfigScope` with `ckconfig.Command`
+separately when they want configuration operations alongside definition commands.
 
 The three maintained consumers live at `examples/core`,
 `integrations/ckconfig/examples/simple`, and

docs/roadmap/configkit.md

@@ -36,8 +36,8 @@ disclosure; CommandKit owns selection, coordination, adaptation, and presentatio
 | --- | --- |
 | Core module | Go 1.26.0; captured commands, typed bindings, dispatch, outcomes, help, and version. No ConfigKit dependency. ReleaseKit v0.4.0 is the declared maintainer tool. |
 | `integrations/ckconfig` | Requires ConfigKit v0.7.1. `Scope`, `Suite`, `FromConfigKit`, and `AppCommand` expose independently declared validate/show/sources/explain/diff capabilities. |
-| `integrations/ckprompt` | Requires ConfigKit v0.7.1 and PromptKit v0.12.0. It depends on ckconfig's public scope contracts and adapts engine configuration plus named definitions; its ConfigKit scope does not declare comparison. |
+| `integrations/ckprompt` | The later PromptKit adoption selects PromptKit v0.14.0 and ConfigKit v0.7.1. It adapts engine configuration and exposes native comparison, prompt/profile catalogs, and named definitions through ckconfig and core contracts. |
-| Comparison status | ConfigKit-backed `config diff` is implemented. The [CLI reference](../cli.md#compare-configuration-selections), integration GoDoc, and [implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/20e19b95694f7fdfd5c342ec4d543152986623dc/docs/roadmap/implementation.md) own current contracts and evidence. PromptKit comparison remains deferred. |
+| Comparison status | ConfigKit-backed `config diff` and PromptKit engine-scope comparison are implemented. The [CLI reference](../cli.md#compare-configuration-selections) and [PromptKit adoption record](promptkit.md) describe current behavior; the [implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/20e19b95694f7fdfd5c342ec4d543152986623dc/docs/roadmap/implementation.md) records ConfigKit completion. |
 
 The ConfigKit adapter acquires typed `*configkit.Result[T]` values and exposes
 effective, source, and explanation facets through `View` for ordinary operations.
@@ -62,9 +62,11 @@ and [comparison contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/com
 
 ## Dependency adoption and ownership
 
-Both integration modules now select ConfigKit v0.7.1 and carry normal dependency
+Both integration modules select ConfigKit v0.7.1 and carry normal dependency
-metadata for their actual graphs. Consumer Go minimums remain 1.26.0, the selected
+metadata for their actual graphs. Consumer Go minimums remain 1.26.0, and the
-release toolchain remains 1.26.8, and PromptKit remains v0.12.0 for this work.
+selected release toolchain remains 1.26.8. At completion of this ConfigKit work,
+ckprompt still selected PromptKit v0.12.0; the later PromptKit adoption is tracked
+in [promptkit.md](promptkit.md).
 Core continues to have no ConfigKit or optional-integration dependency.
 
 ConfigKit's declared tool requirement brings ReleaseKit v0.4.1 into the integration

docs/roadmap/deferred.md

@@ -5,8 +5,8 @@ Status: retained future work and unselected proposals; no implementation schedul
 ## Purpose and authority
 
 Completed initial delivery, performance, ReleaseKit upgrade, and remediation
-records have been retired. This document preserves their unfinished capability
+records have been retired. This document preserves remaining deferred
-targets and deferred ideas under the
+capabilities and unselected ideas under the
 [release policy](../policy/release.md#release-documentation-and-preparation).
 The original records remain available in
 [Git history](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap).
@@ -18,13 +18,13 @@ an idea here does not select its syntax, API, priority, or delivery date.
 
 ## Deferred capability targets
 
-### PromptKit configuration comparison
+### PromptKit requirement inspection
 
-ConfigKit-backed `config diff` is implemented by `ckconfig` for scopes that
+PromptKit exposes `Engine.InspectRequirements`, but a standard CommandKit
-declare that capability. `ckprompt.ConfigScope` does not declare comparison.
+operation for requirement inspection remains deferred. Its command syntax,
-Reassess PromptKit's supported public comparison capabilities before planning a
+selection behavior, presentation, and readiness semantics have not been
-PromptKit comparison. Do not reach into ConfigKit internals or infer comparison
+selected. Reassess the owning library's public contract and make those product
-semantics from rendered YAML.
+choices before planning delivery.
 
 ### Comparison extensions
 
@@ -33,16 +33,6 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only
 for a concrete consumer need and a deliberate API/behavior decision under the
 relevant ADRs.
 
-### CAT-01: PromptKit catalogs
-
-List captured prompt/version entries and named profiles through owning public
-catalog APIs, with deterministic reports of loaded definitions. Resource names,
-enumeration details, and report shapes remain future design work.
-
-The initial PromptKit v0.12.0 review did not find public enumeration APIs.
-Reassess current released capabilities before planning delivery. Do not infer
-catalogs by reparsing configuration YAML or inspecting sibling internals.
-
 ## Other deferred proposals
 
 These capabilities remain outside the delivered scope and require a concrete

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Implement PromptKit comparison and catalogs
 
-Status: Stages 1–9 complete; remaining stages are planned.
+Status: Stages 1–10 complete; remaining stages are planned.
 
 ## Scope and authority
 
@@ -583,6 +583,29 @@ Review diffs, links/fragments, examples, and stale statements; run documented
 Markdown whitespace checks. Describe native semantics as upstream-owned. Do not
 promise arbitrary catalog/provider data is safe for public disclosure.
 
+**Completion evidence (2026-10-12)**
+
+- Updated ckprompt GoDoc for native configuration comparison, all four optional
+  callbacks, callback narrowing, selector/input preparation, nil-factory zero
+  values, and catalog YAML defaults. Root and module READMEs now describe the
+  shipped integration.
+- Updated the CLI reference for PromptKit `config diff` and independent prompt
+  and profile catalogs, including selectors, YAML schema/default, empty results,
+  and the owning-library boundary for comparison and catalog membership. It
+  leaves catalog data disclosure with the application/provider.
+- Updated consumer guidance with a narrowing-before-capture example, the
+  internal package overview, and development commands. The PromptKit roadmap now
+  records delivered behavior; the ConfigKit roadmap summary reflects the later
+  PromptKit adoption; and `deferred.md` retains only requirement inspection as a
+  PromptKit capability deferred from this feature.
+- Reviewed the architecture policy and ADRs 0004 and 0008–0012. They remain
+  consistent with the delivered ownership and invocation model; no decision
+  record changes were needed. Historical baseline and ConfigKit completion
+  records remain clearly scoped to their original work.
+- Markdown whitespace checks passed. A local-link and fragment check passed for
+  all ten changed Markdown files. Composed example behavior was exercised and
+  passed with Stage 9's example and complete ckprompt suite checks.
+
 ## Stage 11: Reconcile notices and prepared release notes
 
 **Outcome:** distributed metadata/notices match actual graphs, and unpublished

docs/roadmap/promptkit.md

@@ -1,7 +1,8 @@
 # Adopt PromptKit v0.14.0 and expose comparison and catalogs
 
-Status: accepted feature end state; implementation has not started. Scope,
+Status: comparison, catalogs, and current behavior documentation are implemented.
-ownership, catalog API, and initial presentation choices are settled.
+Dependency notice/release-note reconciliation and complete validation remain in
+the [implementation record](implementation.md), Stages 11–12.
 
 ## Purpose and authority
 
@@ -34,9 +35,7 @@ This roadmap defines the selected end state. The
 [implementation plan](implementation.md) assigns the ordered work and records
 stage completion evidence.
 
-## Current baseline
+## Baseline at commit ab270e2
-
-Baseline: CommandKit commit `ab270e2`.
 
 CommandKit is a prerelease alpha codebase with no existing consumers. The
 maintained consumer examples demonstrate intended usage; this adoption needs no
@@ -48,7 +47,19 @@ consumer migration plan.
 | `integrations/ckconfig` | ConfigKit v0.7.1; independent validate/show/sources/explain/diff capabilities, paired selection/input preparation, and the shared YAML comparison report and delivery path. Report placement uses a report-local mapping index. |
 | `integrations/ckprompt` | PromptKit v0.12.0 and ConfigKit v0.7.1. `ConfigScope` exposes validate/show/sources/explain, without comparison. `Suite` and `FromEngine` expose named prompt/profile inspection; `Command` generates only `promptkit show` children. |
 | Maintained composed consumer | Demonstrates both configuration scopes, app configuration comparison, named prompt/profile inspection, and an application-owned session command. Application configuration caching distinguishes selections and supplied campaign inputs. |
-| Deferred work | PromptKit comparison and catalogs are recorded as future capabilities in [deferred.md](deferred.md). They are targets of this adoption; requirement inspection is deferred separately. |
+| Deferred work | PromptKit comparison and catalogs were future capabilities at this baseline. The later adoption delivers them; requirement inspection remains deferred in [deferred.md](deferred.md). |
+
+## Delivered status
+
+The current repository uses PromptKit v0.14.0. `ConfigScope` declares native
+comparison through `config diff`; `FromEngine` supplies prompt/profile catalog
+and named-inspection callbacks; and `Command` installs only the supplied `list`
+and `show` operations. The maintained composed consumer exercises comparison,
+both catalogs, named inspection, and its application-owned session command.
+Stages 1–10 and their completion evidence are recorded in the
+[implementation plan](implementation.md). Requirement inspection remains
+deferred; distribution reconciliation and complete validation are still pending
+there.
 
 The existing [ckprompt contracts and adapters](../../integrations/ckprompt/adapters.go)
 and [command assembly](../../integrations/ckprompt/command.go) are the starting
@@ -113,8 +124,8 @@ app config diff --scope promptkit --config before.yml --against-config after.yml
 app config diff --scope promptkit --config base.yml --against-overlay candidate
 ```
 
-These are target invocations, not currently implemented PromptKit comparisons.
+These invocations use the existing
-They use the existing [comparison CLI contract](../cli.md#compare-configuration-selections):
+[comparison CLI contract](../cli.md#compare-configuration-selections):
 one scope, left selectors and inherited right overrides, shared applicable domain
 selector values, YAML-only additions/changes/deletions presentation, and success
 for completed comparisons regardless of whether differences exist. There is no
@@ -290,7 +301,10 @@ exact strings; quote through the YAML encoder rather than interpreting
 numeric-looking versions. CommandKit defines these report fields explicitly;
 serialization of an upstream Go struct does not define the CLI schema.
 
-## Work needed from the baseline
+## Selected implementation scope
+
+The sections below record the scope selected for adoption. Implementation status
+and evidence are tracked in the [implementation plan](implementation.md).
 
 ### Dependencies and distribution
 

integrations/ckprompt/README.md

@@ -1,9 +1,8 @@
 # CommandKit ckprompt
 
-`ckprompt` is the optional PromptKit integration for CommandKit. It can adapt
+`ckprompt` is the optional PromptKit integration for CommandKit. It adapts
-PromptKit engine configuration into a `ckconfig.Scope` and create core command
+PromptKit engine configuration, native comparison, prompt/profile catalogs, and
-declarations for named prompt and profile inspection. Importing it does not
+named inspection. Importing it does not install either command family.
-install either command family.
 
 ## Module
 
@@ -17,15 +16,16 @@ for callback, input, state, and acquisition contracts.
 ## Example
 
 Add `ckprompt.ConfigScope(loadEngine)` to the scopes passed to
-`ckconfig.Command` when the application wants PromptKit engine configuration in
+`ckconfig.Command` when the application wants PromptKit engine configuration
-the `config` family. Install `ckprompt.Command(ckprompt.FromEngine(loadEngine))`
+and native comparison in the `config` family. Install
-separately for named prompt and profile inspection. `FromEngine` supplies
+`ckprompt.Command(ckprompt.FromEngine(loadEngine))` separately for prompt/profile
-PromptKit-backed callbacks; applications may provide their own callbacks with
+catalogs and named inspections. `FromEngine` supplies all four PromptKit-backed
-`ckprompt.Suite`. CommandKit-owned inspection code does not execute prompts,
+callbacks; applications may narrow them before capture or provide their own
-contact model providers, or resolve credentials; application loaders and direct
+callbacks with `ckprompt.Suite`. CommandKit-owned inspection and listing code
-callbacks retain their own effects. See the
+does not execute prompts or contact model providers; application loaders and
+direct callbacks retain their own effects. See the
 [CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#promptkit-definition-inspection)
-for the inspection boundary and report semantics. The maintained
+for operator commands and report semantics. The maintained
 [composed example](examples/composed) shows complete application wiring.
 
 ## License and attribution

integrations/ckprompt/adapters.go

@@ -36,15 +36,18 @@ type ProfileRequest struct {
 // construction failures.
 // Factory results and callback effects remain caller-owned: Command does not
 // deep-copy arbitrary objects or repair aliases returned by factories.
+// A reached operation prepares one input, applies its captured selectors, and
+// checks the input before creating state and calling the selected provider.
 // Factories are not invoked during construction, installation, help, or version,
 // and need not run after failure.
 type Suite[I, S any] struct {
-	// NewInput is called once when definition input preparation is reached,
+	// NewInput is called once when definition or catalog input preparation is
-	// before applying selectors and calling CheckInput.
+	// reached, before applying selectors and calling CheckInput.
 	// If nil, input is the zero value of I, including nil for pointer types.
 	NewInput func() I
-	// NewState is called once when inspection is reached, after input checks
+	// NewState is called once when an inspection or catalog callback is reached,
-	// pass. If nil, state is the zero value of S, including nil for pointer types.
+	// after input checks pass. If nil, state is the zero value of S, including
+	// nil for pointer types.
 	NewState func() S
 	// Selectors declares the original typed flags accepted by definition and
 	// catalog commands.
@@ -69,11 +72,12 @@ type Suite[I, S any] struct {
 type engineLoader[I, S any] func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)
 
 // ConfigScope adapts PromptKit's captured configuration inspection to the
-// standard configuration commands. The loader is not called during declaration
+// standard configuration commands, including native comparison when the scope
-// construction or installation; it is called only when a config operation
+// declares Diff. The loader is not called during declaration construction or
-// selects the promptkit scope, with that operation's input and shared state.
+// installation; it is called only when a config operation selects the
-// PromptKit diagnostics and error identity are returned through ckconfig's
+// promptkit scope, with that operation's input and shared state. PromptKit
-// acquisition contract.
+// diagnostics and supported error identity are returned through ckconfig's
+// acquisition and comparison contracts.
 func ConfigScope[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) ckconfig.Scope[I, S] {
 	scope := ckconfig.Scope[I, S]{
 		Name:       "promptkit",
@@ -139,11 +143,12 @@ func promptKitContextError(ctx context.Context) error {
 	return ctx.Err()
 }
 
-// FromEngine creates prompt and profile catalog and inspection callbacks backed
+// FromEngine supplies callbacks for prompt and profile catalogs and named
-// by a PromptKit engine loader. It does not call the loader during construction.
+// inspections backed by a PromptKit engine loader. It does not call the loader
-// Each selected operation passes its context, supplied selection, initialized
+// during construction. Each selected operation passes its context, supplied
-// input, and shared invocation state to the loader before calling PromptKit's
+// selection, initialized input, and shared invocation state to the loader before
-// public listing or inspection method. A nil loader is retained as an adapter
+// calling PromptKit's public listing or inspection method. The callbacks can be
+// narrowed before Command captures them. A nil loader is retained as an adapter
 // issue.
 func FromEngine[I, S any](load func(context.Context, ckconfig.Selection, I, S) (*promptkit.Engine, error)) Suite[I, S] {
 	if load == nil {

integrations/ckprompt/command.go

@@ -31,11 +31,16 @@ type catalogInput[I any] struct {
 	selected  I
 }
 
-// Command captures the optional PromptKit catalog and named inspection trees
+// Command captures the optional PromptKit catalog and named inspection
-// and adds only the operations present in suite. It adds no configuration
+// callbacks and adds only supplied operations, generating list and show groups
-// family; callers compose ConfigScope independently. Construction and
+// independently. An absent suite claims no namespace; attached construction
-// installation do not run suite callbacks. Suite documents invocation input
+// issues remain reportable. It adds no configuration family; callers compose
-// and state initialization, zero values, and caller ownership of returned objects.
+// ConfigScope independently. Construction, installation, help, and version do
+// not run suite factories or providers. Suite documents invocation input and
+// state initialization, zero values, and caller ownership of returned objects.
+// Catalog commands accept config/overlay selection and suite selectors, and
+// render YAML with `yaml` as the only format and default. Named-show formats are
+// unchanged.
 func Command[I, S any](suite Suite[I, S]) commandkit.Command {
 	if suite.InspectPrompt == nil && suite.InspectProfile == nil && suite.ListPrompts == nil && suite.ListProfiles == nil {
 		command := commandkit.NoCommand()

integrations/ckprompt/doc.go

@@ -1,4 +1,5 @@
-// Package ckprompt provides optional PromptKit configuration and named
+// Package ckprompt provides optional PromptKit configuration comparison,
-// definition inspections for CommandKit. Importing ckprompt installs neither
+// definition catalogs, and named inspections for CommandKit. Importing ckprompt
-// family; callers compose its declarations with core and ckconfig explicitly.
+// installs neither family; callers compose its declarations with core and
+// ckconfig explicitly.
 package ckprompt