Restore public API reference documentation

diagnostic.go

@@ -7,14 +7,18 @@ import (
 )
 
 // LoadError reports safe structured diagnostics for a failed configuration load.
+// It intentionally does not expose or unwrap parser and application errors.
 type LoadError struct{ value *engine.LoadError }
 
+// Error implements error without rendering diagnostic messages or input values.
 func (e *LoadError) Error() string {
 	if e == nil || e.value == nil {
 		return "configkit: configuration load failed"
 	}
 	return e.value.Error()
 }
+
+// Diagnostics returns a deep copy of the error's canonical diagnostics.
 func (e *LoadError) Diagnostics() []Diagnostic {
 	if e == nil || e.value == nil {
 		return nil
@@ -29,6 +33,8 @@ func (e *LoadError) Diagnostics() []Diagnostic {
 	}
 	return result
 }
+
+// Sources returns a deep copy of sources discovered before loading failed.
 func (e *LoadError) Sources() []SourceInfo {
 	if e == nil || e.value == nil {
 		return nil
@@ -44,7 +50,8 @@ func (e *LoadError) Sources() []SourceInfo {
 	return result
 }
 
-// WriteDiagnostics writes diagnostics in canonical order.
+// WriteDiagnostics writes diagnostics in canonical order. It escapes terminal
+// control characters and propagates writer errors, including short writes.
 func WriteDiagnostics(output io.Writer, diagnostics []Diagnostic) error {
 	return engine.WriteDiagnostics(output, toEngineDiagnostics(diagnostics))
 }

docs/roadmap/remediation.md

@@ -2,7 +2,7 @@
 
 Review baseline: `5dc7e18`. Reviewed commits `f81def9` through `5dc7e18` against
 `eb7de8e`, the agreed [roadmap](public.md), and [implementation plan](implementation.md).
-Status: two open findings; F1 and F2 resolved. Review evidence below describes the
+Status: one open finding; F1–F3 resolved. Review evidence below describes the
 original baseline; resolution records describe the subsequent fixes.
 
 The previous provenance finding remains resolved; its record is preserved at
@@ -108,7 +108,13 @@ the everyday check.
 
 ## F3 — Restore consumer contracts on public Go declarations
 
-Priority: medium. Status: open.
+Priority: medium. Status: resolved.
+
+Resolution: restored the baseline comments on root source, path, secret, and
+diagnostic declarations. The complete `go doc -all .` output now matches the
+pre-refactor `eb7de8e` reference, with no missing declarations or contract prose.
+Documentation-link and whitespace checks passed. No behavior or new guarantee
+was introduced.
 
 ### Evidence and impact
 

path.go

@@ -5,7 +5,12 @@ import (
 )
 
 // Path identifies a configuration value using YAML field names. Its textual form
-// is a JSON Pointer. Paths are immutable; the zero value is the root path.
+// 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.
+//
+// Paths are immutable. The zero value is the root path.
 type Path struct {
 	value engine.Path
 }
@@ -13,7 +18,9 @@ type Path struct {
 // Keys constructs a path of mapping keys. Keys with no arguments returns the root path.
 func Keys(keys ...string) Path { return Path{value: engine.Keys(keys...)} }
 
-// ParsePath parses a JSON Pointer while preserving context-dependent numeric tokens.
+// ParsePath parses a JSON Pointer. Numeric tokens remain unresolved until schema
+// or document traversal determines whether the containing value is a mapping or
+// sequence.
 func ParsePath(pointer string) (Path, error) {
 	value, err := engine.ParsePath(pointer)
 	return Path{value: value}, err
@@ -23,6 +30,7 @@ func ParsePath(pointer string) (Path, error) {
 func (p Path) Key(key string) Path { return Path{value: p.value.Key(key)} }
 
 // Index returns a new path with index appended as a sequence-index segment.
+// A negative index produces an invalid path that configuration operations reject.
 func (p Path) Index(index int) Path { return Path{value: p.value.Index(index)} }
 
 // String returns the path's canonical JSON Pointer spelling.

secret.go

@@ -18,6 +18,7 @@ type Secret struct {
 }
 
 // SecretEnv constructs an unresolved environment-backed secret reference.
+// Invalid names are reported if the reference survives a configuration load.
 func SecretEnv(name string) Secret { return Secret{name: name, specified: true} }
 
 // EnvName returns the public environment-variable name.

source.go

@@ -13,13 +13,15 @@ type Source struct{ value engine.Source }
 // File returns a source that reopens path for every load attempt.
 func File(path string) Source { return Source{value: engine.File(path)} }
 
-// Bytes snapshots data immediately.
+// Bytes snapshots data immediately. Label must be nonempty and safe to display;
+// constructor problems are reported when the source is consumed.
 func Bytes(label string, data []byte) Source { return Source{value: engine.Bytes(label, data)} }
 
-// Reader returns a single-use source. Copies share the same single-use claim.
+// Reader returns a single-use source. ConfigKit consumes input but never closes it.
+// Copies of the returned Source share the same single-use claim.
 func Reader(label string, input io.Reader) Source { return Source{value: engine.Reader(label, input)} }
 
-// NoSource explicitly selects defaults-only input.
+// NoSource explicitly selects a defaults-only input. It creates no source record.
 func NoSource() Source { return Source{value: engine.NoSource()} }
 
 func (s Source) toEngine() engine.Source { return s.value }