Make consumer documentation easier to follow

path.go

@@ -4,8 +4,12 @@ import (
 	"go.maximumdirect.net/configkit/internal/engine"
 )
 
-// Path identifies a configuration value using YAML field names. Its textual form
-// is a JSON Pointer: the root is empty, ~ escapes as ~0, and / escapes as ~1.
+// Path names a value inside configuration. For example, Keys("servers").Index(0)
+// names the first server, while Keys("servers", "0") names a literal mapping key.
+// They have the same pointer text but distinct key/index intent.
+//
+// Its textual form is a JSON Pointer: the root is empty, ~ escapes as ~0, and /
+// escapes as ~1.
 // Paths are semantic rather than filesystem or URL paths: empty, dot, dot-dot,
 // percent-containing, and numeric keys retain their literal meaning. Parsed
 // numeric tokens are resolved only when traversal knows their containing type.