e5.2.0 Decoder and loader refactored, bug fixes.

doc/access.md

@@ -95,6 +95,37 @@ cfg, _ := config.NewBuilder().
 fmt.Println(config.Server.Port)
 ```
 
+### GetTyped
+
+Retrieves a single configuration value and decodes it to the specified type.
+
+```go
+import "time"
+
+// Returns an int, converting from string "9090" if necessary.
+port, err := config.GetTyped[int](cfg, "server.port")
+
+// Returns a time.Duration, converting from string "5m30s".
+timeout, err := config.GetTyped[time.Duration](cfg, "server.timeout")
+```
+
+### ScanTyped
+
+A generic wrapper around `Scan` that allocates, populates, and returns a pointer to a struct of the specified type.
+
+```go
+// Instead of:
+// var dbConf DBConfig
+// if err := cfg.Scan("database", &dbConf); err != nil { ... }
+
+// You can write:
+dbConf, err := config.ScanTyped[DBConfig](cfg, "database")
+if err != nil {
+    // ...
+}
+// dbConf is a *DBConfig```
+```
+
 ### Type-Aware Mode
 
 ```go

doc/builder.md

@@ -152,9 +152,10 @@ cfg, _ := config.NewBuilder().
 
 ### WithValidator
 
-Add validation functions that run after loading:
+Add validation functions that run *before* the target struct is populated. These validators operate on the raw `*config.Config` object and are suitable for checking required paths or formats before type conversion.
 
 ```go
+// Validator runs on raw, pre-decoded values.
 cfg, _ := config.NewBuilder().
     WithDefaults(defaults).
     WithValidator(func(c *config.Config) error {
@@ -172,6 +173,34 @@ cfg, _ := config.NewBuilder().
     Build()
 ```
 
+For type-safe validation, see `WithTypedValidator`.
+
+### WithTypedValidator
+
+Add a type-safe validation function that runs *after* the configuration has been fully loaded and decoded into the target struct (set by `WithTarget`). This is the recommended approach for most validation logic.
+
+The validation function must accept a single argument: a pointer to the same struct type that was passed to `WithTarget`.
+```go
+type AppConfig struct {
+    Server struct {
+        Port int64 `toml:"port"`
+    } `toml:"server"`
+}
+
+var target AppConfig
+
+cfg, err := config.NewBuilder().
+    WithTarget(&target).
+    WithFile("config.toml").
+    WithTypedValidator(func(conf *AppConfig) error {
+        if conf.Server.Port < 1024 || conf.Server.Port > 65535 {
+            return fmt.Errorf("port %d is outside the valid range", conf.Server.Port)
+        }
+        return nil
+    }).
+    Build()
+```
+
 ### WithFile
 
 Set configuration file path: