Document PromptKit comparison and catalogs

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
-does not install PromptKit prompt or profile definition commands.
+to expose PromptKit engine configuration through these handlers. The scope
+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
-`--scope promptkit` is a usage error.
+When an application installs `ckprompt.ConfigScope(loadEngine)`, the PromptKit
+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;
-source or provenance differences alone do not create a change. The report is one
-YAML document with `additions`, `changes`, and `deletions` in that order.
-Additions and changes preserve semantic paths and contain safe right-side values.
-Deletions contain canonical JSON Pointer paths. Explicit null is a value; it is
-not a deletion. Changed sequences and native structural replacement regions stay
-atomic.
+For ConfigKit-backed scopes, ConfigKit compares frozen effective typed values
+after defaults and resolution; source or provenance differences alone do not
+create a change. PromptKit delegates its native comparison to ConfigKit. The
+report is one YAML document with `additions`, `changes`, and `deletions` in that
+order. Additions and changes preserve semantic paths and contain right-side
+values provided by the native comparison. Deletions contain canonical JSON
+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
-redaction and hidden-change metadata: a reported masked region changed, but that
-does not mean every member inside it changed. Marker-looking public strings stay
-ordinary YAML values. An empty comparison succeeds with this shape:
+appear even when its two safe snapshots are equal. For those ConfigKit-backed
+comparisons, the report omits separate redaction and hidden-change metadata: a
+reported masked region changed, but that does not mean every member inside it
+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`.