Make consumer documentation easier to follow

diff.go

@@ -2,14 +2,13 @@ package configkit
 
 import "go.maximumdirect.net/configkit/internal/engine"
 
-// Difference describes one canonical changed region between two successful
-// loads. Left is the earlier value and Right is the later value. Each snapshot
-// is detached; Present distinguishes absence from an explicit null, and
-// Redacted reports whether combined sensitivity affected that side. Mappings
-// are compared recursively, while sequences are reported as atomic values.
-// Records are ordered by canonical JSON pointer. HiddenChanged indicates that
-// a value concealed by combined sensitivity changed, without revealing which
-// concealed member changed.
+// Difference describes one changed value or subtree between two successful loads.
+// Left is the earlier value and Right is the later value. Snapshots are copies;
+// Present distinguishes absence from explicit null. Redacted reports hiding
+// based on sensitivity from either load. Mappings compare by key; a changed
+// sequence is reported as a whole value. Records are ordered by canonical JSON
+// pointer. HiddenChanged reports an actual hidden change, without identifying
+// the hidden member. Redaction alone does not set it.
 type Difference struct {
 	Path          Path
 	Left          ValueSnapshot
@@ -17,8 +16,9 @@ type Difference struct {
 	HiddenChanged bool
 }
 
-// Diff compares the frozen effective values of two successful loads of the
-// same configuration type. It does not reread sources, environment variables,
+// Diff compares the saved final values of two successful loads of the same
+// configuration type, independently of later changes to Result.Config.
+// It does not reread sources, environment variables,
 // or rerun defaults or resolvers. Equal values produce no records even when
 // their sources, defaults, or resolution histories differ. Credential contents
 // are not compared: typed secret references compare by reference name only.