docs: align API docs with current implementation

[asadijabar]

What

• Fix the README validation example so it compiles by adding the missing Database.Host field in README.md.
• Update docs/api-reference.md to include missing exported API details: SourceWithKeys, ErrWatchNotSupported, env: tag support, and snapshot path helpers (ExpandPath, ExpandPathWithTime).
• Clarify documented behavior in docs/api-reference.md and docs/configuration-sources.md for watch semantics (initial snapshot + 100ms debounce), JSON dump shape when combining AsJSON() and WithSources(), and where key lowercasing occurs.

Why

• The docs were out of sync with current public APIs and runtime behavior.
• The README contained a non-compiling snippet in the validation section.
• Aligning docs with implementation reduces onboarding friction and integration mistakes.

Type

• Fix
• Feature
• Docs
• Performance
• Breaking change

Testing

Executed:

go test ./...
make ci

Results:

• go test ./... passed.
• make ci passed (format, vet, tests, lint) with reported coverage 81.5%.

Checklist

• Tests pass (go test ./...)
• Formatted (gofmt -s -w .)
• No vet warnings (go vet ./...)
• Coverage maintained (>70%)
• Added tests if needed
• Updated docs if needed

Added tests if needed: N/A — docs-only changes; no runtime behavior was modified.

---

For reviewers: Does this align with Rigging's philosophy of simplicity and zero dependencies?

[Copilot]

Pull request overview

This pull request aligns documentation with the current implementation by adding missing API documentation and clarifying runtime behavior. The changes are documentation-only and do not modify any code behavior.

Changes:

• Fixed non-compiling validation example in README by adding the required Database.Host field
• Added documentation for exported APIs: SourceWithKeys, ErrWatchNotSupported, env: tag, and path helpers (ExpandPath, ExpandPathWithTime)
• Clarified watch semantics, JSON dump format when combining options, key lowercasing behavior, and tag precedence rules

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
README.md	Added missing Database.Host field to validation example to make it compile correctly
docs/api-reference.md	Added documentation for SourceWithKeys, ErrWatchNotSupported, env: tag, path helpers, watch behavior, JSON dump shape, and tag precedence clarifications
docs/configuration-sources.md	Clarified key lowercasing behavior during loader merge and added watch behavior notes (initial snapshot + debounce)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.