Update versions, dependencies, documentation

Author: MimoJanra

CONTRIBUTING.md

@@ -129,7 +129,7 @@ Examples of bad comments:
 
 ```go
 // This function loads the config
-func Load[T any](sources ...Source) (T, error) { ... }
+func Load[T any](sources ...Source) (*T, error) { ... }
 
 // Increment the counter
 counter++
@@ -191,7 +191,7 @@ PORT must be between 1 and 65535, got 99999
    ```go
    type Source interface {
        Name() string
-       Lookup(field *FieldInfo) (any, bool, error)
+       Lookup(ctx context.Context, field *FieldInfo) (any, bool, error)
    }
    ```
 

README.md

@@ -55,7 +55,7 @@ No custom error handling. No secret leaks in logs. Types are checked at compile
 ✅ **Secret redaction** — mark sensitive fields with `secret:"true"`, they're automatically hidden  
 ✅ **Multiple sources** — load from YAML, env, JSON, TOML, Kubernetes, AWS, Vault with explicit precedence  
 ✅ **Lightweight** — only 2 core dependencies, cloud integrations are optional modules  
-✅ **Production-ready** — v0.9.0 with full test coverage, used in real services
+✅ **Production-ready** — v1.0.0 with full test coverage and API stability guarantee
 
 ```go
 type Config struct {
@@ -145,14 +145,14 @@ go get github.com/MimoJanra/confkit/aws@latest
 
 ---
 
-## Breaking Changes in v0.10.0
+## Breaking Changes in v1.0.0
 
 **`Load[T]` now returns `(*T, error)` instead of `(T, error)` (pointer)**
 
 This aligns with Go idioms for larger configs. Go automatically dereferences pointers for field access, so most code works unchanged:
 
 ```go
-// v0.10+ — works exactly the same
+// v1.0+ — works exactly the same
 cfg, err := confkit.Load[Config](confkit.FromEnv())
 log.Printf("Port: %d", cfg.Port)  // auto-dereference, works fine
 ```
@@ -319,10 +319,16 @@ Built-in sources — pass any combination, first one to provide a value wins per
 
 ```go
 confkit.FromYAML(path string) Source
+confkit.FromYAMLOptional(path string) Source
+confkit.FromYAMLFiles(paths ...string) Source
 confkit.FromJSON(path string) Source
+confkit.FromJSONFiles(paths ...string) Source
 confkit.FromTOML(path string) Source
+confkit.FromTOMLFiles(paths ...string) Source
 confkit.FromEnv() Source
 confkit.FromFlags() Source
+confkit.FromFlagsWithArgs(args []string) Source
+
 ```
 
 Optional sources (separate `go get` per module):
@@ -347,10 +353,10 @@ etcd.FromEtcdWithPrefix(endpoints []string, prefix string) confkit.Source
 
 // go get confkit/aws
 aws.FromAWSSSMParameterStore(pathPrefix string) confkit.Source
-aws.FromAWSSSMParameterStoreWithTTL(pathPrefix string, ttl time.Duration) confkit.Source
+aws.FromAWSSSMParameterStoreWithTTL(pathPrefix string, cacheTTL time.Duration) confkit.Source
 aws.FromAWSSecretsManager(secretName string) confkit.Source
 aws.FromAWSSecretsManagerWithRegion(secretName, region string) confkit.Source
-aws.FromAWSSecretsManagerWithOptions(secretName, region string, ttl time.Duration) confkit.Source
+aws.FromAWSSecretsManagerWithOptions(secretName, region string, cacheTTL time.Duration) confkit.Source
 aws.FromAWSSecretsManagerMultiRegion(secretName string, regions []string) confkit.Source
 aws.FromAWSSSMParameterStoreMultiRegion(pathPrefix string, regions []string) confkit.Source
 ```
@@ -408,15 +414,25 @@ func Load[T any](sources ...Source) (*T, error)
 
 // Load with fine-grained options (validators, middleware, interpolation depth)
 func LoadWithOptions[T any](options ...Option) (*T, error)
+func LoadContext[T any](ctx context.Context, sources ...Source) (*T, error)
+func LoadWithOptionsContext[T any](ctx context.Context, options ...Option) (*T, error)
+func ValidateOnly[T any](ctx context.Context, options ...Option) (*T, error)
+func MustLoad[T any](sources ...Source) *T
+func MustLoadContext[T any](ctx context.Context, sources ...Source) *T
 
 // Load and set up a file watcher in one call
 func LoadWithWatcher[T any](filePath string, sources ...Source) (*T, *ConfigWatcher, error)
 
 // Option constructors
 func WithSource(source Source) Option
-func WithValidator(name string, fn func(reflect.Value) error) Option
+func WithValidator(name string, fn func (reflect.Value) error) Option
+func WithModelValidator[T any](fn func (*T) error) Option
 func WithMiddleware(fn MiddlewareFunc) Option
+func WithAuditLogger(fn AuditLogger) Option
+func WithLoadHook(fn LoadHookFunc) Option
+func WithContext(ctx context.Context) Option
 func WithInterpolationMaxDepth(depth int) Option
+
 ```
 
 ---
@@ -459,7 +475,8 @@ type Config struct {
 }
 ```
 
-- Error messages show `<redacted>` instead of the value
+- Error messages show `<redacted>` for secret fields
+- Validation values are redacted as `***REDACTED***`
 - `DumpConfig` substitutes `"***REDACTED***"`
 - Safe to log the output of `Explain(err)` and `DumpConfig` without leaking credentials
 
@@ -587,9 +604,12 @@ type Source interface {
 // FieldInfo fields available to your Lookup implementation:
 // .Name         string            — "Password"
 // .Path         string            — "Database.Password"
+// .Type         reflect.Type
+// .Value        reflect.Value
 // .Tags         map[string]string — all struct tags
 // .IsSecret     bool
 // .HasDefault   bool
+// .IsNested     bool
 // .AncestorTags []map[string]string — tags of parent structs
 
 // Helper for returning a permanently-errored source (e.g. from a constructor):
@@ -614,6 +634,15 @@ md := schema.GenerateMarkdown[Config]()
 help := schema.GenerateCLIHelp[Config]()
 ```
 
+
+## Safe Dump API
+
+```go
+func Dump[T any](cfg T, opts ...DumpOption) ([]byte, error)
+func DumpString[T any](cfg T, opts ...DumpOption) string
+func DumpYAML[T any](cfg T, opts ...DumpOption) ([]byte, error)
+```
+
 ---
 
 ## Supported Types
@@ -626,6 +655,7 @@ help := schema.GenerateCLIHelp[Config]()
 | `float32` / `float64`                             | decimal                           |
 | `bool`                                            | `true` `false` `1` `0` `yes` `no` |
 | `time.Duration`                                   | `"5s"` `"1m30s"` `"2h"`           |
+| `time.Time`                                       | RFC3339 `"2006-01-02T15:04:05Z07:00"` |
 | `[]string`                                        | comma-separated `"a,b,c"`         |
 | `[]int`                                           | comma-separated `"1,2,3"`         |
 | `map[string]string` / `map[string]int` etc.       | `KEY=val,KEY2=val2` format        |

confkit_test.go

@@ -294,7 +294,7 @@ func TestExplainError(t *testing.T) {
 	}
 
 	explained := Explain(err)
-	if !strings.Contains(explained, "<redacted>") {
+	if !strings.Contains(explained, "***REDACTED***") {
 		t.Errorf("expected secret to be redacted, got: %s", explained)
 	}
 }
@@ -655,7 +655,7 @@ func TestValidationWithSecretRedaction(t *testing.T) {
 	})
 
 	formatted := report.Format()
-	if !strings.Contains(formatted, "<redacted>") {
+	if !strings.Contains(formatted, "***REDACTED***") {
 		t.Errorf("expected secret to be redacted in error, got: %s", formatted)
 	}
 	if strings.Contains(formatted, "super-secret-12345") {

docs/api/index.md

@@ -12,7 +12,7 @@ Complete reference for confkit's public API.
 ### Load
 
 ```go
-func Load[T any](sources ...Source) (T, error)
+func Load[T any](sources ...Source) (*T, error)
 ```
 
 Loads configuration from the provided sources and returns a fully typed, validated config or an error.
@@ -43,7 +43,7 @@ if err != nil {
 ### LoadWithOptions
 
 ```go
-func LoadWithOptions[T any](options ...Option) (T, error)
+func LoadWithOptions[T any](options ...Option) (*T, error)
 ```
 
 Advanced loading with functional options for custom validators, middleware, and interpolation configuration.
@@ -90,7 +90,7 @@ cfg, err := confkit.LoadWithOptions[Config](
 ### LoadWithWatcher
 
 ```go
-func LoadWithWatcher[T any](filePath string, sources ...Source) (T, *ConfigWatcher, error)
+func LoadWithWatcher[T any](filePath string, sources ...Source) (*T, *ConfigWatcher, error)
 ```
 
 Loads configuration and returns a watcher for hot-reloading when files change.

docs/comparison/envconfig.md

@@ -235,4 +235,4 @@ cfg, err := confkit.Load[Config](
 ## Maturity
 
 - **envconfig:** Lightweight, stable, minimal changes
-- **confkit:** Production-ready v0.9.0, actively developed with cloud integrations
+- **confkit:** Production-ready v1.0.0, actively developed with cloud integrations

docs/comparison/koanf.md

@@ -314,4 +314,4 @@ value := k.Get("some.dynamic.key")
 ## Maturity
 
 - **koanf:** Stable, widely used for flexible configurations
-- **confkit:** Production-ready v0.9.0, focused on typed, validated, struct-first config
+- **confkit:** Production-ready v1.0.0, focused on typed, validated, struct-first config

docs/comparison/viper.md

@@ -162,4 +162,4 @@ If you're moving from Viper to confkit:
 ## Maturity
 
 - **Viper:** Mature, widely used, large community
-- **confkit:** Production-ready v0.9.0, focused on a specific use case (type-safe, validated, struct-first)
+- **confkit:** Production-ready v1.0.0, focused on a specific use case (type-safe, validated, struct-first)

docs/docs/index.md

@@ -7,36 +7,34 @@ title: Documentation
 
 ## Getting Started
 
-- **[Installation & Quick Start](./getting-started/)** — Set up confkit in 5 minutes
-- **[Core Concepts](./concepts/)** — Understanding sources, validation, and error handling
+- **[Installation & Quick Start](./getting-started.md)** — Set up confkit in 5 minutes
+- **[Configuration Sources](./sources.md)** — Environment variables, files, cloud services
 - **[Examples](https://github.com/MimoJanra/confkit/tree/main/examples)** — Production-ready code samples
 
 ## Usage Guides
 
-- **[Configuration Sources](./sources/)** — Environment variables, files, cloud services
-- **[Validation](./validation/)** — Built-in rules and custom validators
-- **[Error Handling](./errors/)** — Human-readable error messages and debugging
-- **[Advanced Features](./advanced/)** — Interpolation, options, hot reload
+- **[Validation](./validation.md)** — Built-in rules and custom validators
+- **[Defaults & Fallbacks](./defaults.md)** — Setting default values and merging sources
+- **[Schema Generation](./schema-generation.md)** — Generate JSON Schema and CLI help
+- **[Secret Redaction](./secret-redaction.md)** — Secure handling of sensitive fields
+- **[Hot Reload](./hot-reload.md)** — File watching and configuration updates
 
 ## Upgrading
 
-- **[Migration Guide: v0.10.0](./migration-v0.10.md)** — Breaking changes and how to migrate from v0.9
+- **[Migration Guide: v1.0.0](./migration-v0.10.md)** — Breaking changes and how to migrate from v0.9
 
 ## Cloud & Enterprise
 
-- **[Kubernetes](./cloud/kubernetes/)** — ConfigMap and Secret sources
-- **[AWS](./cloud/aws/)** — SSM Parameter Store and Secrets Manager
-- **[HashiCorp](./cloud/hashicorp/)** — Vault, Consul, and etcd
-- **[Secret Rotation](./enterprise/rotation/)** — Automatic credential refresh
+- **[Kubernetes Integration](./recipes/kubernetes-configmap.md)** — ConfigMap and Secret sources
+- **[AWS Integration](./recipes/aws-secrets-manager.md)** — SSM Parameter Store and Secrets Manager
+- **[HashiCorp Integration](./recipes/vault.md)** — Vault, Consul, and etcd
+- **[Environment-Only Config](./recipes/env-only.md)** — Simple env var loading
+- **[CLI Flags](./recipes/cli-flags.md)** — Command-line argument parsing
 
-## Versions
+## Latest Version
 
-- **[v0.5](./v0.5/)** — Latest stable (full feature set)
-- **[v0.4](./v0.4/)** — Production with cloud sources
-- **[v0.3](./v0.3/)** — Enhanced DX with interpolation
-- **[v0.2](./v0.2/)** — Schema generation and TOML
-- **[v0.1](./v0.1/)** — Core MVP
+**v1.0.0** — Full API stability, production-ready release with comprehensive documentation
 
 ## Philosophy
 
-[Design principles and philosophy behind confkit](./philosophy/)
+- **[Design Principles](../philosophy.md)** — Design decisions and architecture behind confkit

docs/docs/installation.md

@@ -138,7 +138,7 @@ func main() {
     if err != nil {
         log.Fatal(err)
     }
-    log.Printf("Port: %d", cfg.Port)  // cfg is *Config pointer (v0.10+)
+    log.Printf("Port: %d", cfg.Port)  // cfg is *Config pointer (v1.0+)
 }
 ```
 
@@ -151,10 +151,10 @@ go run main.go
 
 ## Version Notes
 
-**v0.10.0 (current stable):**
+**v1.0.0 (current stable):**
 - `Load[T]` returns `(*T, error)` instead of `(T, error)` — pointer return (breaking change from v0.9)
 - Most code works unchanged due to Go auto-dereference behavior
-- See [Migration Guide](./migration-v0.10.md) for details
+- See [Migration Guide](./migration-v1.0.md) for details
 
 **v0.9:**
 - `Load[T]` returned `(T, error)` — value return
@@ -210,7 +210,7 @@ If you see version conflicts with other dependencies (especially AWS SDK):
 
 ```bash
 go mod tidy
-go get github.com/MimoJanra/confkit@v0.9.0  # pin explicit version
+go get github.com/MimoJanra/confkit@v1.0.0  # pin explicit version
 ```
 
 ## Next Steps

docs/docs/migration-v0.10.md

@@ -1,11 +1,11 @@
 ---
 layout: default
-title: Migration Guide - v0.10.0
+title: Migration Guide - v1.0.0
 ---
 
-# Migration Guide: v0.9 → v0.10
+# Migration Guide: v0.9 → v1.0
 
-v0.10.0 introduces breaking changes. This guide explains what changed and how to migrate.
+v1.0.0 introduces breaking changes. This guide explains what changed and how to migrate.
 
 ## Breaking Changes
 
@@ -17,7 +17,7 @@ cfg, err := confkit.Load[Config](confkit.FromEnv())
 // cfg type: Config
 ```
 
-**After (v0.10):**
+**After (v1.0):**
 ```go
 cfg, err := confkit.Load[Config](confkit.FromEnv())
 // cfg type: *Config (pointer)
@@ -42,7 +42,7 @@ log.Printf("Port: %d", (*cfg).Port) // ✅ Explicit dereference (unnecessary)
 func Handler(cfg Config) {}
 handler(cfg)  // ERROR: type mismatch
 
-// Fixed (v0.10+)
+// Fixed (v1.0+)
 func Handler(cfg *Config) {}
 handler(cfg)  // ✅ Works
 
@@ -98,7 +98,7 @@ cfg, err := otel.Load[Config](tracer, sources...)
 // cfg type: *Config (pointer)
 ```
 
-## New Features in v0.10
+## New Features in v1.0
 
 ### FromYAMLOptional()
 
@@ -183,7 +183,7 @@ func main() {
     server := &Server{Config: cfg}  // Store in struct
 }
 
-// v0.10 — same code, no changes needed!
+// v1.0 — same code, no changes needed!
 func main() {
     cfg, err := confkit.Load[Config](confkit.FromEnv())
     if err != nil {
@@ -211,4 +211,4 @@ A: No, but migration is simple. Most code works unchanged due to Go's auto-deref
 
 - See **[FromYAMLOptional()](./sources.md#yaml-files)** for optional file loading
 - See **[Automatic snake_case mapping](./sources.md#automatic-snake_case-mapping-v010)** for field mapping
-- See **[Examples](https://github.com/MimoJanra/confkit/tree/main/examples)** for production-ready code with v0.10
+- See **[Examples](https://github.com/MimoJanra/confkit/tree/main/examples)** for production-ready code with v1.0