Document configuration comparison behavior

docs/cli.md

@@ -230,6 +230,63 @@ environment-variable name; effective and historical secret fragments remain
 redacted. Empty location, inheritance, history, reason, and dependency lists are
 serialized as `[]`.
 
+### Compare configuration selections
+
+`config diff` compares two independently loaded selections for one scope that
+declares comparison. 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.
+`--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;
+an explicit empty string overrides it and remains supplied. Equal selections are
+allowed and both reached sides are loaded.
+
+YAML is the only format and the default. Explicit `--format yaml` is accepted;
+`text` and other formats are usage errors. For example:
+
+```text
+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 ""
+```
+
+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.
+
+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:
+
+```yaml
+additions: {}
+changes: {}
+deletions: []
+```
+
+The reduced report is a partial safe view, not a reloadable configuration or an
+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.
+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. Comparison
+diagnostics identify their left/right side and source legend. The adapter loads
+left before right, retains left diagnostics if right loading fails, and gathers
+both loads' diagnostics before native comparison. The complete report is
+prepared before writing. Cancellation and preparation failures leave report
+output empty; an output error or short write uses the existing incomplete-report
+delivery outcome.
+
 ## PromptKit definition inspection
 
 Applications can install prompt and profile inspection independently with